Runners and the vault

A runner is a small Polo program that does the actual work against a system: it signs in to a cloud account, plans Terraform, reads a cluster, or checks a URL. The vault is where a workspace stores keys and tokens once and uses them by name. Both are tabs on the Connections page.

What a runner does

Polo sends a runner signed requests, such as “plan this stack” or “apply this approved plan”. The runner checks each one against its own settings and refuses anything else. There are two kinds.

	Polo’s default runner	Your own runner
Where it runs	In Polo, one per workspace	On a machine or cluster you choose
To install	Nothing	One Docker or kubectl command
What it can reach	Cloud accounts you connect with a key or a role, for the connection types it serves	Anything that machine can reach, including systems inside your network or VPN
Where credentials live	In Polo, encrypted	A runner can use the access its machine already has, so nothing is stored in Polo

The default runner appears on the Runners tab as Runs in Polo, nothing to install. It starts when a request needs it. It is offered only where your Polo deployment has it turned on.

When you need your own runner

Use Polo’s default runner when you connect a cloud account with an access key, a role Polo may assume, or a Google service account key.

Add your own runner when:

• the system is inside a private network or behind a VPN;
• you want an uptime monitor to check a private URL;
• you want to open a Kubernetes cluster in Polo and make changes in it (the runner is installed in the cluster as its Polo agent);
• you do not want to store cloud credentials in Polo, and prefer the access the runner’s machine already has, such as an EC2 instance role;
• the connection type is not offered on the default runner. The Add connection dialog lists Polo’s default runner (nothing to install) under Runs on only for what it can serve.

Add a runner

Only an administrator can add one.

1. Open Connections → Runners and press Add a runner.
2. Enter a Runner name. Name it after the machine it runs on.
3. Press Add runner. Polo shows a token and the commands to start the runner, with the token filled in.
4. Copy the token now. Polo shows it once and keeps only a fingerprint.
5. Start the runner on a machine that has Docker and can reach the systems Polo should work with. Choose one way:
   • the plungo runner start command, which checks Docker and starts the runner;
   • the docker run command shown, to start it yourself;
   • the kubectl command shown, to install it in a Kubernetes cluster as that cluster’s Polo agent.
6. Wait until the runner shows as Connected, then choose it under Runs on (or Signs in from) when you add a connection.

The runner connects out to Polo over HTTPS. Open no port and give it no public address.

Caution

Anyone who has the runner token can collect this workspace’s runner requests. Store it like a password.

A runner started this way takes its settings from Polo, so there is no settings file to write. That is simple, but it means whoever controls the workspace in Polo decides what that runner reads with its machine’s access. A runner you configure by hand with its own settings file only does what that file allows, and Polo cannot widen it. Hand-configured runners are described in Runners.

Runner states

What the list shows	Meaning
Connected	The runner is connected to Polo now
Not connected	It is not connected. Checks and requests that need it fail until it is back.
Never connected	It has never reached Polo. Check that it was started with its token and can reach Polo.
Last connected, with a time	When Polo last heard from it

Each runner also lists what it serves. Press Activity to read what the runner reported: when it started, what it serves and why it stopped. Press Remove to delete a runner; its token stops working, and connections that run on it can no longer be reached.

A runner on an older version may need an update before it can run uptime checks or carry a live Kubernetes session. The page says so when that is the case.

The vault

The vault holds keys and tokens you store once and use by name. Polo encrypts each value and never shows it again, to a person or to an agent.

Add a secret

1. Open Connections → Vault and press Add a secret.
2. Enter a Name using letters, digits, dots, dashes or underscores, such as aws-runner-key.
3. Optionally say What it is for.
4. Enter the Value and press Add secret.

Use a secret

When you add a connection, choose the secret under Take the key from instead of typing the key. A Terraform skill can take a GitHub access token for a private repository from the vault in the same way. The vault list shows which connections use each secret.

Replace or delete a secret

• Replace value stores a new value. Every connection that uses the secret uses the new value at once. Change it on the other side too (the runner or the service), or those connections stop working.
• Delete removes the value from Polo; it cannot be recovered. A secret that an enabled connection uses cannot be deleted.

Who can do what

	Administrator	Operator, Viewer	Agents and models
See secret names	Yes	Yes	No
Add, replace, delete	Yes	No	No
Read a value	No	No	No

Agents never read a secret. They use it only through a connection whose key it is. MCP access tokens cannot reach the vault either.

Where your credentials are

• Default runner: the access key, role or service account key you enter is kept encrypted in Polo and used only by your workspace’s runner.
• Your own runner, settings from Polo: it can use the access its machine already has, so nothing needs to be stored in Polo.
• Your own hand-configured runner: cloud, registry and database credentials stay on the runner. Polo keeps only the key it signs requests with.

In every case, use the narrowest access that does the job. Read-only access is enough to map an account; changes need the specific permissions named when you connect it. See Connect a cloud account.