Secret stores

The runner reads your service credentials from your secret manager, at boot, and keeps them in memory only. Nothing is written to disk, and nothing is custodied outside your infrastructure.

RUNNER_SECRET_STORE_MODE=env    # default, development
RUNNER_SECRET_STORE_MODE=aws    # AWS Secrets Manager
RUNNER_SECRET_STORE_MODE=vault  # HashiCorp Vault (KV v2 or v1)

All three backends implement the same minimal interface, get(name), so switching between them changes nothing else in the runner.

Which one to pick

On AWS: use aws. It is native, and authentication comes from the workload’s own identity.

On GCP, or anywhere else: use vault. There is no native GCP Secret Manager backend — if you are on GCP, Vault is the supported path. Note this is orthogonal to obtaining credentials for GCP for the connectors, which works natively through Workload Identity (RUNNER_GCP_CRED_MODE=chain, in Cloud credentials).

env is not a production path: keys sit in plaintext in the workload definition.

Two different layers, and don't conflate them

Layer 1 is this page: where secrets live. Layer 2 is how the runner obtains cloud credentials for read connectors: RUNNER_AWS_CRED_MODE and RUNNER_GCP_CRED_MODE, in Cloud credentials. They are orthogonal.

env: development

Reads from the process environment. It’s the default, and Compose feeds it through pass-through: the value comes from the shell, injected by your secret manager or by runner.secrets.env via npm run dev:runner:file.

Fine for local development. In production, prefer one of the two below.

aws: AWS Secrets Manager

RUNNER_SECRET_STORE_MODE=aws
# RUNNER_SECRETS_MANAGER_REGION=us-east-1   # absent ⇒ SDK default resolution
# RUNNER_SECRETS_MANAGER_PREFIX=rootpilot/  # prefixes the SecretId

Resolves through the SDK’s default credential chain (IAM role, workload identity, IRSA) with no static keys. It’s the natural path for a runner on EKS or ECS.

PREFIX prefixes the SecretId, so a secret named DD_API_KEY with prefix rootpilot/ is fetched as rootpilot/DD_API_KEY.

vault: HashiCorp Vault (KV v2 and v1)

RUNNER_SECRET_STORE_MODE=vault
RUNNER_VAULT_ADDR=https://vault.example.com

# token auth
RUNNER_VAULT_AUTH=token
RUNNER_VAULT_TOKEN=…

# or AppRole auth
RUNNER_VAULT_AUTH=approle
RUNNER_VAULT_ROLE_ID=…
RUNNER_VAULT_SECRET_ID=…

# or Kubernetes auth — the method that belongs in a cluster
RUNNER_VAULT_AUTH=kubernetes
RUNNER_VAULT_K8S_ROLE=rootpilot
# optional; default below
RUNNER_VAULT_K8S_TOKEN_PATH=/var/run/secrets/tokens/vault/token

On Kubernetes, prefer kubernetes over approle

AppRole requires handing a static secret_id to the container — exactly the kind of credential the RootPilot Agent exists not to carry. Kubernetes login uses the pod’s own projected service-account token: the workload’s identity is the credential, and nothing static ships in the image.

The pod must mount the token, and the audience has to be what your Vault expects:

volumes:
  - name: vault-token
    projected:
      sources:
        - serviceAccountToken:
            path: token
            audience: vault      # whatever your Vault role requires
            expirationSeconds: 3600
volumeMounts:
  - name: vault-token
    mountPath: /var/run/secrets/tokens/vault
    readOnly: true

Use a mount separate from the enrollment token. The two projections carry different audiences; reusing one file makes one side reject a legitimate token, and the error reads as a bad credential.

HTTP access to the KV API. The mount version (v2 or v1) is detected on the first read — a v1 mount is no longer mistaken for a missing secret. Additional options:

Variable	Default	What for
RUNNER_VAULT_NAMESPACE	none	Vault Enterprise.
RUNNER_VAULT_KV_MOUNT	secret	KV mount. v2 and v1 are detected automatically.
RUNNER_VAULT_KV_FIELD	value	Which field of the secret to return.
RUNNER_VAULT_PREFIX	''	Prefixes the logical path.

The schema refuses incomplete configuration at boot:

RUNNER_SECRET_STORE_MODE=vault requires RUNNER_VAULT_ADDR
vault auth requires RUNNER_VAULT_TOKEN (token), RUNNER_VAULT_ROLE_ID+RUNNER_VAULT_SECRET_ID (approle) or RUNNER_VAULT_K8S_ROLE (kubernetes)

A missing secret is not an error

In both remote backends, “not found” (ResourceNotFoundException on AWS, 404 on Vault) resolves to undefined, not an exception.

That’s what makes the lazy model work: you configure only the connectors you use, and the rest simply drop out of the served set. A missing secret does not bring down the boot.

The signal is in the boot log:

connector not served {connectorId: "azion", missing: ["AZION_TOKEN"]}

A typo in a key name looks exactly like a missing key

The azion connector declares AZION_TOKEN. If your vault holds AZION_API_TOKEN, the result is identical to having nothing: the connector drops out of the served set, silently. Check the exact names in Connector credentials.

Per-connector scoping

The runtime scopes the secret store per connector: each one sees only the secrets it declared in its own manifest. A connector cannot read another’s credential, even running in the same process. It’s the first of the runtime’s four guarantees.

What never happens

Inviolable policy

Customer credentials are never custodied outside the customer's infrastructure. The runner reads them from their secret manager at boot and keeps them in memory only. There is no path in the code where a credential crosses the boundary to the control-plane.