Skip to main content
Internal

Secrets

SLAW encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references.

Custody boundaries​

SLAW protects secret values up to the moment they are handed to an agent or workload:

  • Storage: values are encrypted at rest by the active provider. The local provider keeps them encrypted with a key that never leaves the host.
  • Transport: values are decrypted server-side and injected into the agent process environment, SSH command env, sandbox driver, or HTTP request immediately before the call. SLAW does not return decrypted values to the UI.
  • Audit: each resolution records a non-sensitive event (secret id, version, provider id, consumer, outcome) — never the value or provider credentials.

Once a value reaches the consuming process, SLAW can no longer guarantee secrecy. The agent can read the value, write it to its own logs, or pass it downstream. Treat any secret you bind to an agent as exposed to that agent. Limit blast radius with bindings (bind only what each agent needs), short-lived credentials where the provider supports them, and rotation when a transcript or downstream system might have captured a value.

Using secrets in runs​

Creating a squad secret does not automatically create an environment variable. You use a secret by binding it into an agent, project, environment, or plugin configuration field that supports secret references.

For agent and project environment variables:

  1. Create or link the secret in Squad Settings → Secrets.
  2. Open the agent's Environment variables field, or the project's Env field.
  3. Add the environment variable key the process expects, such as GH_TOKEN or OPENAI_API_KEY.
  4. Set the row source to Secret, select the stored secret, and choose latest or a pinned version.

At runtime, SLAW resolves the selected secret server-side and injects the resolved value under the env key from the binding row. Project env applies to every issue run in that project; when a project env key matches an agent env key, the project value wins before SLAW injects its own SLAW_* runtime variables.

Default provider: local_encrypted​

Secrets are encrypted with a local master key stored at:

~/.slaw/instances/default/secrets/master.key

This key is auto-created during onboarding and never leaves your machine. SLAW best-effort enforces 0600 permissions when it creates or loads the key file; slaw doctor warns when the file is readable by group or other users.

caution

Back up the key file together with database backups. A database backup without the key cannot decrypt local secrets, and a key backup without the database metadata cannot restore named secret versions.

Configuration​

Onboarding writes default secrets config:

npx slaw onboard

Update or validate secrets settings:

npx slaw configure --section secrets
npx slaw doctor
npx slaw secrets doctor --squad-id <squad-id>

Environment overrides​

VariableDescription
SLAW_SECRETS_MASTER_KEY32-byte key as base64, hex, or raw string
SLAW_SECRETS_MASTER_KEY_FILECustom key file path
SLAW_SECRETS_STRICT_MODESet to true to enforce secret refs

Strict mode​

When strict mode is enabled, sensitive env keys (matching *_API_KEY, *_TOKEN, *_SECRET) must use secret references instead of inline plain values.

SLAW_SECRETS_STRICT_MODE=true

Recommended for any deployment beyond local trusted. Authenticated deployments default strict mode on unless explicitly overridden by configuration or SLAW_SECRETS_STRICT_MODE=false.

Provider vaults​

A provider vault is a named, squad-scoped configuration that points secret material at a supported provider backend. Each squad can configure multiple vaults — including more than one per provider family — and pick a default vault per family for new secret operations. Configure them under Squad Settings → Secrets → Provider vaults.

Provider vaults store only non-sensitive routing config: region, project id, namespace, prefix, KMS key id, mount path, and similar. The API, UI, and activity log never accept, return, or display provider credential values. Provider credentials live in deployment infrastructure identity (instance profile, IRSA, ECS task role, AWS_PROFILE), not in SLAW squad secrets.

The built-in AWS provider supports managed and external-reference secrets today; GCP Secret Manager and HashiCorp Vault are marked coming_soon — you can save draft config, but runtime operations are locked until those modules ship.

note

For the full provider-vault model — status lifecycle, per-vault health checks, AWS remote import, and backup/restore — see the secrets reference and doc/SECRETS-AWS-PROVIDER.md in the repo.

Secret references in agent config​

Agent environment variables use secret references:

{
  "env": {
    "ANTHROPIC_API_KEY": {
      "type": "secret_ref",
      "secretId": "8f884973-c29b-44e4-8ea3-6413437f8081",
      "version": "latest"
    }
  }
}

The server resolves and decrypts these at runtime, injecting the real value into the agent process environment.

Next steps​