Credentials

The Agent Runner reads no secret from environment variables or a .env file. Secrets come in two classes: a handful of bootstrap secrets the runner needs before any page exists, provided as files, and the operational secrets agents work with, which Agent Pool administrators manage in Administration → Credentials and which live encrypted in the runner’s secret store. Everything that is not secret — the Polarion URL, the LLM gateway URL, PocketBase email, sandbox settings — is plain configuration in agentic.env.

Dev Preview — will be fixed for production

Agent tokens are created by hand in Polarion and pasted in, and the runner does not know when a token expires. See Known limitations.

Overview

flowchart LR
  subgraph B["<b>Bootstrap secrets</b> — files at /run/secrets, before the runner starts"]
    direction TB
    F1["<b>secret_key</b><br/><small>encrypts the secret store</small>"]:::ext
    F2["<b>admin_token</b><br/><small>runner's Polarion administrator</small>"]:::ext
    F3["<b>pocketbase_admin_password</b><br/><small>PocketBase superuser</small>"]:::ext
    F4["<b>opensandbox_api_key</b><br/><small>empty file = no sandboxes</small>"]:::ext
  end
  subgraph O["<b>Operational secrets</b> — Administration → Credentials, no restart"]
    direction TB
    S1["<b>Model key</b><br/><small>LLM gateway key for every agent</small>"]:::pol
    S2["<b>Agent tokens</b><br/><small>one Polarion token per agent</small>"]:::pol
    S3["<b>Connected systems</b><br/><small>set when a connection is registered</small>"]:::pol
  end
  A["<b>Administrator</b><br/><small>pastes a value, once</small>"]:::you --> O
  B --> R["<b>Agent Runner</b><br/><small>reads files on start</small>"]:::run
  O --> ST["<b>Encrypted store</b><br/><small>AES (Fernet) with secret_key</small>"]:::run
  ST --> R
  R --> U["<b>Agent runs</b><br/><small>each agent signs in as its own user</small>"]:::ok
  classDef pol fill:#dcecec,stroke:#0d6e6e,stroke-width:1.2px,color:#12302f
  classDef run fill:#ece5fb,stroke:#7c3aed,stroke-width:1.2px,color:#2b1d4f
  classDef ext fill:#e3ebfb,stroke:#2563eb,stroke-width:1.2px,color:#16264a
  classDef you fill:#fdf0d8,stroke:#b7791f,stroke-width:1.2px,color:#4a3210
  classDef ok fill:#e3f2e7,stroke:#1f7a3d,stroke-width:1.2px,color:#143d22
  classDef bad fill:#fbe4e2,stroke:#b3261e,stroke-width:1.2px,color:#4d1612
  classDef mute fill:#f1f4f6,stroke:#8a96a3,stroke-width:1.2px,color:#2a3440

Bootstrap secrets (files)

These are what the runner needs to start, before it can serve any page. Each one is a file, one per secret, that the runner reads at /run/secrets/<name>. The file name is the name of the setting.

File	What it is
secret_key	The key that encrypts the runner’s secret store. Generate it once: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())". Keep it in your secret management, separate from backups of the store.
admin_token	A Polarion personal access token of the runner’s own administrator user. The runner validates callers and reads the Agent Pool with it.
pocketbase_admin_password	The PocketBase superuser password. The email is configuration (POCKETBASE_ADMIN_EMAIL in agentic.env).
opensandbox_api_key	The OpenSandbox API key. An empty file means sandboxes are off; see Sandboxes.

How the files get there depends on where the runner runs:

• Docker Compose: the shipped docker-compose.yml declares the four files under secrets: and takes them from ./secrets/<name> next to the compose file. Create the folder and the four files with mode 0600.
• Kubernetes: a Secret volume, a CSI secrets-store driver or External Secrets mounted at /run/secrets works unchanged — the runner only reads files named like the settings.

Rotation of a bootstrap secret = replace the file and restart the runner.

Caution

secret_key is what makes the store readable. Changing it makes every stored credential unreadable: you then set the model key, every agent token and every connection credential again in Administration → Credentials.

Operational secrets (Administration → Credentials)

Open the Agent Pool project and choose Administration → Credentials. The page lists what the runner needs, in three groups, and whether each item is set (with the time of the last change and who made it) or missing (marked red). Values are stored encrypted in the runner’s secret store with secret_key, read by the runner when it needs them, and never shown again: the paste field is write-only, and no page or API returns a value.

Group	Items	Test
Model provider	The model key: the key for the LLM gateway every agent talks through.	Sends a one-token request through the gateway.
Agent tokens	A checklist per agent: 1 · its Polarion user exists (with a Create user button when not), 2 · a personal access token is set (with the link to the token page in Polarion), 3 · the token signs in. The list is derived from the agents in the pool: a new agent shows the open steps until the token is pasted and tested. Test all checks every agent at once.	Signs in to Polarion as that agent.
Connected systems	The credentials of MCP servers and git hosts, set when a connection is registered (see Connections).	Check server now on the connection.

For each item:

• Set stores a value for the first time; Replace rotates it: paste the new value and agents use it on their next run, no restart needed. Then revoke the old value where it was issued.
• Test checks the stored value against the real system: the model key answers a one-token request, an agent token signs in as that agent.
• Every agent row links to the Polarion page where an administrator creates a personal access token for that user (Create a token for bot-… in Polarion ↗, later Tokens of bot-…). Polarion offers no API for creating tokens, so this stays a copy-and-paste step; the licence of a new user is assigned in Polarion too.

Every write is made as the administrator who pastes the value and is recorded with their name and time, which is what the page shows next to set.

What is missing

Missing items are marked red on the page. The runner’s status (GET /status) and the preflight check report them too: the Model gateway check fails without a model key, and the Bot tokens check names every agent in the pool that has no token or whose token no longer signs in. An agent without a token does not get work; a run that needs a missing credential ends with an error that names the item.

Configuration that is not secret

agentic.env (copy agentic.env.example from the repository) holds the plain configuration:

Setting	Meaning
POLARION_URL	Polarion base URL, ending in /polarion.
POLARION_VERIFY_TLS	false only if Polarion uses a certificate the runner can’t verify.
CORS_ORIGINS	JSON list of browser origins allowed to call the runner (the Polarion server).
POCKETBASE_ADMIN_EMAIL	PocketBase superuser email; the password is the secret file.
LLM_GATEWAY_URL	Base URL of your model provider or company LLM gateway; the key is set in Administration → Credentials.
MODEL_OVERRIDE	Testing only: run every agent on this model.
SANDBOX_EDGE_HOST, SANDBOX_MAX, SANDBOX_*	Sandbox settings, see Sandboxes; the API key is the secret file.

See Installation for the full list.

Related

• Installation · Operations · Security · Agent Pool