Configuration
The Runops agent is a small, reliable, and cross-platform task runner that makes it easy to run tasks on your own infrastructure. Its main responsibilities are polling Runops for work, running tasks, and reporting back the status code and output log of the task. Here is what it looks like:

The picture looks complicated but you can get this done in 10-15 minutes going slow. We will break down each piece to make it easier. We need to setup 3 components inside your Cloud to setup the agent:
- Internal System
- Secrets Manager
- The agent
#
Internal System
This is the easiest part. It consists of creating a credential in your internal system to be used by Runops. The procedure varies, it could be database, a Kubernetes cluster, or a AWS account. We'll use a Mysql database as the example for this guide, so I went ahead and created a user in a demo database so you can follow along, here it is:
note
Yes, this is the password to a working database. But don't worry, it's read-only and there is nothing sensitive in there.
#
Secrets Manager
The Runops agent pulls credentials from the Secrets Manager of your choice, all within your infrastructure. Secrets never leave your infrastructure.
Each Target need a new secret record. In this guide we will use a Mysql database in the examples, but you can update the values to match the integration you need.
- Environment Variables
- 🔵 AWS Secrets Manager
- 🔴 AWS Secrets Manager
- Hashicorp Vault
The easiest way to configure Secrets is to add them as Environment Variables to the Agent. Start with this one and layer the Secrets Manager integrations explained in the other tabs later.
All you need to do here is to add the contents of the config to an Environment Variable in the Agent:
We built a script that handles all the AWS setup for you in a single command. If you want to understand what is inside and how it works, take the red pill (red tab) and don't use the script. Otherwise just paste this in your terminal:

#
Do you want to know what it is?It's important that you run all these commands in the same terminal window as we will save values from some commands and use them in later commands.
#
1. First we add the credentials of our database to the Secrets Manager:#
2. Then we need to provide a way for the agent to read this secret when running Tasks:Let's create a user in AWS for Runops:
Then we need a policy that enables this user to read the credentials:
And lastly we attach this policy to the user through a role:
#
Tying it all togetherThe agent requires configurations from your Secrets Manager and to link it to your Runops account. After finishing the Credentials configuration of your Secrets Manager you should have all the values for this step. Let's export the variables with the required configurations to make your deployment easier:
The VAULT_AUTH_METHOD
variable is how the runner is authenticating into Vault.
Currently, only kubernetes-account-service
is available, but other login methods
will be available in the future.
Both k8s (account-service) and vault needs to be configured for this method to work.
You can find more details here: https://www.vaultproject.io/docs/auth/kubernetes
#
Agent Deployment
note
Finish the Secrets Manager setup before proceeding.
- Environment Variables
- AWS Secrets Manager
#
Create the TargetLastly we need to link the agent to Runops API.
Congrats! Now the Tasks of this Target will use the new agent! We can run a SQL Task to try it out:
#
Running Multiple AgentsThis is done via TAGS.
An agent will only run tasks from targets whose tags
field match the TAGS environment variable of the agent.
If an agent is deployed with an environment variable like TAGS=prod
, then all targets whose field tags
match the value prod
are executed by that agent. Multiple targets can have the same tags
.
However, an agent MUST have a unique TAGS across the organisation. This means that only one agent can be deployed with TAGS=prod
.
If a second agent tries to start with the same tags, the api will return an error and agent will exit.
If you already have an agent deployed with TAGS=prod
, then another agent can be deployed with a different TAGS,
for instance, TAGS=dev
. Then, only targets whose tags
field match the value dev
will be executed by that agent.
- TAGS can be any value that makes sense to the organisation.
- One agent can be deployed without TAGS, and it will run only tasks from targets whose
tags
field is null.
#
Using Existing SecretsIt's possible to map custom keys from your secret manager:
When executing a task with this target, it will add the value of the secret key MYSQL_HOSTNAME
to MYSQL_HOST
,
this allows a smoothly integration with existent keys in case of existent key in the secret manager.
⚠️ In case of malformed JSON configuration it will hang the execution of a task.
#
Enhanced Agent SecurityThe agent is a system that has higher privileges in a private infrastructure, the created tasks are processed and executed through an authentication that maps an api key of an organization, however there's no way to guarantee that task is being executed by an authenticated and authorized user session. This requirement may be important to organizations in which requires this sort of enforcement.
The JWT tokens are kept in memory only during the execution of a task, they are never persisted.
#
Main Benefits- Prevents the execution of tasks without authenticated the user session token
- Enforced with the use of external auth providers (Okta, Auth0, ORY Hydra, etc)
#
Limitations- Slack Tasks / REPL are disabled when this option is set
- Automation of rotating keys is not yet supported
⚠️ Toggling between this feature (JWK_URL=) could be harmful of stale tasks being executed, perform this operation with careful.
#
ConfigurationSet the enviroment variable JWK_URL
containing the public keys of your auth provider before starting the agent, the supported algorithms are RS256
and ECDSA256
.
To enforce authentication using our auth provider:
JWK_URL=https://runops.us.auth0.com/.well-known/jwks.json
#
IntegrationsThe latest agent supports the integrations:
- bash
- hashicorp-vault
- k8s
- k8s-exec
- k8s-apply
- mongodb
- mysql
- mysql-csv
- postgres
- python
- node
- elixir
- rails
- rails-console
- rails-console-ecs
- sql-server
You can find the legacy Agent docs here.