Secrets management
RemoteClaw supports additive SecretRefs so supported credentials do not need to be stored as plaintext in configuration.
Goals and runtime model
Secrets are resolved into an in-memory runtime snapshot.
- Resolution is eager during activation, not lazy on request paths.
- Startup fails fast when an effectively active SecretRef cannot be resolved.
- Reload uses atomic swap: full success, or keep the last-known-good snapshot.
- SecretRef policy violations (for example OAuth-mode auth profiles combined with SecretRef input) fail activation before runtime swap.
- Runtime requests read from the active in-memory snapshot only.
- After the first successful config activation/load, runtime code paths keep reading that active in-memory snapshot until a successful reload swaps it.
- Outbound delivery paths also read from that active snapshot (for example Discord reply/thread delivery and Telegram action sends); they do not re-resolve SecretRefs on each send.
This keeps secret-provider outages off hot request paths.
Agent-access boundary
SecretRefs protect credentials from being persisted in supported config and generated model surfaces, but they are not a process-isolation boundary. If a plaintext credential remains on disk in a path the agent can read, the agent can bypass API-level redaction by using file or shell tools to inspect that file.
For production deployments where agent-accessible files are in scope, treat SecretRef migration as complete only when all of these are true:
- supported credentials use SecretRefs instead of plaintext values
- legacy plaintext residue has been scrubbed from
remoteclaw.json,auth-profiles.json,.env, and generatedmodels.jsonfiles remoteclaw secrets audit --checkis clean after the migration- any remaining unsupported or rotating credentials are protected by operating system isolation, container isolation, or an external credential proxy
This is why the audit/configure/apply workflow is a security migration gate, not just a convenience helper.
Active-surface filtering
SecretRefs are validated only on effectively active surfaces.
- Enabled surfaces: unresolved refs block startup/reload.
- Inactive surfaces: unresolved refs do not block startup/reload.
- Inactive refs emit non-fatal diagnostics with code
SECRETS_REF_IGNORED_INACTIVE_SURFACE.
Gateway auth surface diagnostics
When a SecretRef is configured on gateway.auth.token, gateway.auth.password, gateway.remote.token, or gateway.remote.password, gateway startup/reload logs the surface state explicitly:
active: the SecretRef is part of the effective auth surface and must resolve.inactive: the SecretRef is ignored for this runtime because another auth surface wins, or because remote auth is disabled/not active.
These entries are logged with SECRETS_GATEWAY_AUTH_SURFACE and include the reason used by the active-surface policy, so you can see why a credential was treated as active or inactive.
Onboarding reference preflight
When onboarding runs in interactive mode and you choose SecretRef storage, RemoteClaw runs preflight validation before saving:
- Env refs: validates env var name and confirms a non-empty value is visible during setup.
- Provider refs (
fileorexec): validates provider selection, resolvesid, and checks resolved value type. - Quickstart reuse path: when
gateway.auth.tokenis already a SecretRef, onboarding resolves it before probe/dashboard bootstrap (forenv,file, andexecrefs) using the same fail-fast gate.
If validation fails, onboarding shows the error and lets you retry.
SecretRef contract
Use one object shape everywhere:
{ source: "env" | "file" | "exec", provider: "default", id: "..." }Supported SecretInput fields also accept exact string shorthands:
```json5"${OPENAI_API_KEY}""$OPENAI_API_KEY"```
Validation:
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`- `id` must match `^[A-Z][A-Z0-9_]{0,127}$`Validation:
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`- `id` must be an absolute JSON pointer (`/...`)- RFC6901 escaping in segments: `~` => `~0`, `/` => `~1`Validation:
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`- `id` must match `^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$` (supports selectors such as `secret#json_key`)- `id` must not contain `.` or `..` as slash-delimited path segments (for example `a/../b` is rejected)Provider config
Define providers under secrets.providers:
{ secrets: { providers: { default: { source: "env" }, filemain: { source: "file", path: "~/.remoteclaw/secrets.json", mode: "json", // or "singleValue" }, vault: { source: "exec", command: "/usr/local/bin/remoteclaw-vault-resolver", args: ["--profile", "prod"], passEnv: ["PATH", "VAULT_ADDR"], jsonOnly: true, }, }, defaults: { env: "default", file: "filemain", exec: "vault", }, resolution: { maxProviderConcurrency: 4, maxRefsPerProvider: 512, maxBatchBytes: 262144, }, },}Request payload (stdin):
```json{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }```
Response payload (stdout):
```jsonc{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret```
Optional per-id errors:
```json{ "protocolVersion": 1, "values": {}, "errors": { "providers/openai/apiKey": { "message": "not found" } }}```File-backed API keys
Do not put file:... strings in the config env block. The env block is
literal and non-overriding, so file:... is not resolved.
Use a file SecretRef on a supported credential field instead:
{ secrets: { providers: { xai_key_file: { source: "file", path: "~/.remoteclaw/secrets/xai-api-key.txt", mode: "singleValue", }, }, }, models: { providers: { xai: { apiKey: { source: "file", provider: "xai_key_file", id: "value" }, }, }, },}For mode: "singleValue", the SecretRef id is "value". For
mode: "json", use an absolute JSON pointer such as
"/providers/xai/apiKey".
See SecretRef credential surface for the config fields that accept SecretRefs.
Exec integration examples
Requirements:
- Bitwarden Secrets Manager CLI (`bws`) installed on the Gateway host.- `BWS_ACCESS_TOKEN` available to the Gateway service.- `PATH` passed to the resolver, or `BWS_BIN` set to the absolute `bws` binary path.
```json5{ secrets: { providers: { bws: { source: "exec", command: "/usr/local/bin/remoteclaw-bws-resolver.mjs", passEnv: ["BWS_ACCESS_TOKEN", "PATH", "BWS_BIN"], jsonOnly: true, }, }, }, models: { providers: { openai: { baseUrl: "https://api.openai.com/v1", models: [{ id: "gpt-5", name: "gpt-5" }], apiKey: { source: "exec", provider: "bws", id: "remoteclaw/providers/openai/apiKey", }, }, }, },}```
The resolver batches requested ids, runs `bws secret list`, and returnsvalues for matching secret `key` fields. Use keys that satisfy the execSecretRef id contract, such as `remoteclaw/providers/openai/apiKey`; env-varstyle keys with underscores are rejected before the resolver runs. If morethan one visible Bitwarden secret has the same requested key, the resolverfails that id as ambiguous instead of choosing one. After updating config,verify the resolver path:
```bashremoteclaw secrets audit --allow-exec``````js#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process");
let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => { stdin += chunk;});process.stdin.on("error", (err) => { process.stderr.write(`${err.message}\n`); process.exit(1);});process.stdin.on("end", () => { let request; try { request = JSON.parse(stdin || "{}"); } catch (err) { process.stderr.write(`Failed to parse request: ${err.message}\n`); process.exit(1); }
const passBin = process.env.PASS_BIN || "pass"; const values = {}; const errors = {};
for (const id of request.ids ?? []) { const result = spawnSync(passBin, ["show", id], { encoding: "utf8" }); if (result.status === 0) { values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? ""; } else { errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() }; } }
process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});```
Then configure the exec provider and point `apiKey` at the `pass` entry path:
```json5{ secrets: { providers: { pass_store: { source: "exec", command: "/usr/local/bin/remoteclaw-pass-resolver", passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"], jsonOnly: true, }, }, }, models: { providers: { openai: { baseUrl: "https://api.openai.com/v1", models: [{ id: "gpt-5", name: "gpt-5" }], apiKey: { source: "exec", provider: "pass_store", id: "remoteclaw/providers/openai/apiKey", }, }, }, },}```
Keep the secret on the first line of the `pass` entry, or customize thewrapper if you want to return the full `pass show` output instead. Afterupdating config, verify both the static audit and the exec resolver path:
```bashremoteclaw secrets audit --checkremoteclaw secrets audit --allow-exec```MCP server environment variables
MCP server env vars configured via plugins.entries.acpx.config.mcpServers support SecretInput. This keeps API keys and tokens out of plaintext config:
{ plugins: { entries: { acpx: { enabled: true, config: { mcpServers: { github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], env: { GITHUB_PERSONAL_ACCESS_TOKEN: { source: "env", provider: "default", id: "MCP_GITHUB_PAT", }, }, }, }, }, }, }, },}Plaintext string values still work. Env-template refs like ${MCP_SERVER_API_KEY} and SecretRef objects are resolved during gateway activation before the MCP server process is spawned. As with other SecretRef surfaces, unresolved refs only block activation when the acpx plugin is effectively active.
Sandbox SSH auth material
The core ssh sandbox backend also supports SecretRefs for SSH auth material:
{ agents: { defaults: { sandbox: { mode: "all", backend: "ssh", ssh: { target: "user@gateway-host:22", identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, }, }, }, },}Runtime behavior:
- RemoteClaw resolves these refs during sandbox activation, not lazily during each SSH call.
- Resolved values are written to temp files with restrictive permissions and used in generated SSH config.
- If the effective sandbox backend is not
ssh, these refs stay inactive and do not block startup.
Supported credential surface
Canonical supported and unsupported credentials are listed in:
Required behavior and precedence
- Field without a ref: unchanged.
- Field with a ref: required on active surfaces during activation.
- If both plaintext and ref are present, ref takes precedence on supported precedence paths.
- The redaction sentinel
__REMOTECLAW_REDACTED__is reserved for internal config redaction/restore and is rejected as literal submitted config data.
Warning and audit signals:
SECRETS_REF_OVERRIDES_PLAINTEXT(runtime warning)REF_SHADOWED(audit finding whenauth-profiles.jsoncredentials take precedence overremoteclaw.jsonrefs)
Google Chat compatibility behavior:
serviceAccountReftakes precedence over plaintextserviceAccount.- Plaintext value is ignored when sibling ref is set.
Activation triggers
Secret activation runs on:
- Startup (preflight plus final activation)
- Config reload hot-apply path
- Config reload restart-check path
- Manual reload via
secrets.reload - Gateway config write RPC preflight (
config.set/config.apply/config.patch) for active-surface SecretRef resolvability within the submitted config payload before persisting edits
Activation contract:
- Success swaps the snapshot atomically.
- Startup failure aborts gateway startup.
- Runtime reload failure keeps the last-known-good snapshot.
- Write-RPC preflight failure rejects the submitted config and keeps both disk config and active runtime snapshot unchanged.
- Providing an explicit per-call channel token to an outbound helper/tool call does not trigger SecretRef activation; activation points remain startup, reload, and explicit
secrets.reload.
Degraded and recovered signals
When reload-time activation fails after a healthy state, RemoteClaw enters degraded secrets state.
One-shot system event and log codes:
SECRETS_RELOADER_DEGRADEDSECRETS_RELOADER_RECOVERED
Behavior:
- Degraded: runtime keeps last-known-good snapshot.
- Recovered: emitted once after the next successful activation.
- Repeated failures while already degraded log warnings but do not spam events.
- Startup fail-fast does not emit degraded events because runtime never became active.
Command-path resolution
Command paths resolve supported SecretRefs locally and in-process. Each CLI
invocation reads the configured env / file / exec providers directly; it
does not query a running gateway, and there is no secrets.resolve gateway RPC.
This keeps command-path resolution independent of gateway availability.
There are two broad behaviors:
-
Strict command paths (for example
remoteclaw memoryremote-memory paths andremoteclaw qr --remotewhen it needs remote shared-secret refs) fail fast when a required SecretRef cannot be resolved locally. -
Read-only command paths (for example
remoteclaw status,remoteclaw status --all,remoteclaw channels status,remoteclaw channels resolve,remoteclaw security audit, and read-only doctor/config repair flows) degrade instead of aborting when a targeted SecretRef cannot be resolved in that command path.- When the gateway is running, these commands read from the active snapshot first.
- If gateway resolution is incomplete or the gateway is unavailable, they attempt targeted local fallback for the specific command surface.
- If a targeted SecretRef is still unavailable, the command continues with degraded read-only output and explicit diagnostics such as “configured but unavailable in this command path”.
- This degraded behavior is command-local only. It does not weaken runtime startup, reload, or send/auth paths.
-
These commands resolve the targeted SecretRef locally for the specific command surface.
-
If a targeted SecretRef is still unavailable, the command continues with degraded read-only output and explicit diagnostics such as “configured but unavailable in this command path”.
-
This degraded behavior is command-local only. It does not weaken runtime startup, reload, or send/auth paths.
Other notes:
- After a backend secret rotation, the long-running gateway refreshes its own in-memory snapshot via
remoteclaw secrets reload; command paths re-resolve from the configured providers on each invocation, so they pick up rotated values directly.
Audit and configure workflow
Default operator flow:
Do not treat the migration as complete until the re-audit is clean. If the audit still reports plaintext values at rest, the agent-access risk is still present even when runtime APIs return redacted values.
If you save a plan instead of applying during configure, apply that saved plan
with remoteclaw secrets apply --from <plan-path> before the re-audit.
- plaintext values at rest (`remoteclaw.json`, `auth-profiles.json`, `.env`, and generated `agents/*/agent/models.json`)- plaintext sensitive provider header residues in generated `models.json` entries- unresolved refs- precedence shadowing (`auth-profiles.json` taking priority over `remoteclaw.json` refs)- legacy residues (`auth.json`, OAuth reminders)
Exec note:
- By default, audit skips exec SecretRef resolvability checks to avoid command side effects.- Use `remoteclaw secrets audit --allow-exec` to execute exec providers during audit.
Header residue note:
- Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).- configures `secrets.providers` first (`env`/`file`/`exec`, add/edit/remove)- lets you select supported secret-bearing fields in `remoteclaw.json` plus `auth-profiles.json` for one agent scope- can create a new `auth-profiles.json` mapping directly in the target picker- captures SecretRef details (`source`, `provider`, `id`)- runs preflight resolution- can apply immediately
Exec note:
- Preflight skips exec SecretRef checks unless `--allow-exec` is set.- If you apply directly from `configure --apply` and the plan includes exec refs/providers, keep `--allow-exec` set for the apply step too.
Helpful modes:
- `remoteclaw secrets configure --providers-only`- `remoteclaw secrets configure --skip-provider-setup`- `remoteclaw secrets configure --agent <id>`
`configure` apply defaults:
- scrub matching static credentials from `auth-profiles.json` for targeted providers- scrub legacy static `api_key` entries from `auth.json`- scrub matching known secret lines from `<config-dir>/.env````bashremoteclaw secrets apply --from /tmp/remoteclaw-secrets-plan.jsonremoteclaw secrets apply --from /tmp/remoteclaw-secrets-plan.json --allow-execremoteclaw secrets apply --from /tmp/remoteclaw-secrets-plan.json --dry-runremoteclaw secrets apply --from /tmp/remoteclaw-secrets-plan.json --dry-run --allow-exec```
Exec note:
- dry-run skips exec checks unless `--allow-exec` is set.- write mode rejects plans containing exec SecretRefs/providers unless `--allow-exec` is set.
For strict target/path contract details and exact rejection rules, see [Secrets Apply Plan Contract](/gateway/secrets-plan-contract).One-way safety policy
Safety model:
- preflight must succeed before write mode
- runtime activation is validated before commit
- apply updates files using atomic file replacement and best-effort restore on failure
Legacy auth compatibility notes
For static credentials, runtime no longer depends on plaintext legacy auth storage.
- Runtime credential source is the resolved in-memory snapshot.
- Legacy static
api_keyentries are scrubbed when discovered. - OAuth-related compatibility behavior remains separate.
Web UI note
Some SecretInput unions are easier to configure in raw editor mode than in form mode.
Related
- Authentication — auth setup
- CLI: secrets — CLI commands
- Environment Variables — environment precedence
- SecretRef Credential Surface — credential surface
- Secrets Apply Plan Contract — plan contract details
- Security — security posture