SecretRef & `anima.json`

A SecretRef is a declarative pointer to a secret. Instead of writing API_KEY=sk-... in a .env file and praying it doesn’t end up in a commit or an LLM’s context window, you write:

{ "source": "anima", "credentialId": "cred_abc123", "field": "apiKey.key" }

The Anima CLI resolves these refs at execution time — the agent composing the command, and the LLM reviewing its output, never see the actual value.

The three sources

Every SecretRef has a source field that determines where the value comes from. Only these three are supported, and that’s deliberate — every additional source is a new place a secret can be misused.

`anima` — Anima Vault

The default. Points at a credential in your vault.

{
  "source": "anima",
  "credentialId": "cred_01HXYZ...",
  "field": "apiKey.key",
  "agentId": "agent_optional"
}

Field	Required	Notes
`credentialId`	yes	The `cred_...` id from the Anima console or `anima vault list`
`field`	yes	Dot-path into the credential (e.g. `apiKey.key`, `login.password`)
`agentId`	no	Explicit agent scope; defaults to the CLI’s authenticated agent

Under the hood the CLI mints a single-use vtk_ token, exchanges it, and the resolved value never touches disk. Every resolution is written to the audit log with the actor’s key type recorded — reveals via a master key (mk_) show up distinctly from agent-scoped accesses.

`env` — Environment variable

Escape hatch for secrets that aren’t yet migrated into Anima (rotating dev tokens, one-off sandbox keys).

{ "source": "env", "name": "MY_DEV_TOKEN" }

Field	Required	Notes
`name`	yes	Must be present in the environment at resolve time

If the variable is unset, the CLI refuses to run. It does not fall back to an empty string — that pattern causes too many “it worked locally but 401’d in prod” bugs.

`exec` — Trusted binary

For dynamic secrets that come from a local tool (AWS STS, op read, gcloud auth print-access-token, short-lived GitHub App tokens).

{
  "source": "exec",
  "command": "aws",
  "args": ["sts", "get-session-token", "--output", "text"]
}

Field	Required	Notes
`command`	yes	Bare binary name or absolute path; shell metacharacters (`;`, `\|`, `, `$`, `&`) are rejected
`args`	no	String array. Spawned with `shell: false` so each element is a literal argv slot
`passEnv`	no	Env var names passed through to the subprocess — everything else is stripped
`cwd`	no	Working directory for the subprocess

Output is captured with a 15-second timeout and a 1 MB buffer cap. If the binary exits non-zero, the CLI refuses to run. The child process starts with a minimal environment: only the variables listed in passEnv, plus PATH so the binary can be found. Be explicit about what your provider needs — e.g. "passEnv": ["HOME", "AWS_PROFILE"] for the AWS CLI.

`anima.json` — putting it together

Drop an anima.json at the root of any project (or any ancestor directory — the CLI walks up from cwd). The shape:

{
  "$schema": "https://docs.useanima.sh/schemas/anima.json",
  "secrets": {
    "GH_TOKEN":    { "source": "anima", "credentialId": "cred_github", "field": "apiKey.key" },
    "DATABASE_URL":{ "source": "env",   "name": "DATABASE_URL" },
    "AWS_KEY":     {
      "source":  "exec",
      "command": "aws",
      "args":    ["sts", "get-session-token", "--output", "text"]
    }
  }
}

The keys (GH_TOKEN, DATABASE_URL, AWS_KEY) are the variable names that will be exposed to whatever command consumes the refs — typically environment variables passed to a child process. The $schema line is optional, but with it any JSON-Schema-aware editor (VS Code out of the box) validates refs and autocompletes fields as you type. The schema is published at docs.useanima.sh/schemas/anima.json.

Using it

# Resolve all refs and exec a subprocess with them in-env
anima vault exec -- gh api /user

# Proxy a single ref through an HTTPS injector
anima vault proxy --cred GH_TOKEN --allow-host api.github.com --port 19840

# Quick lookup — masked metadata only (secret fields are never printed)
anima vault get GH_TOKEN

If the CLI can’t resolve a ref (missing env var, failing exec, deleted vault credential) it refuses to run and emits a structured error — no partial execution, no silent fallback.

Why not just `.env`?

Three reasons:

.env files are static. exec sources pull fresh values on every resolve — matters for STS tokens, SSO-minted GitHub App tokens, and anything else with a lifetime under an hour.
.env files are untyped. A SecretRef is a JSON schema — you get IDE completion, and the CLI can refuse to run if the shape is wrong before the subprocess starts.
.env files don’t participate in the audit log. Every anima-source resolution is attributed to an agent or user and shows up in the console Access Log. Agents that ingest a .env file by accident are a common leak vector; an anima.json commits only references — the values live exclusively in the vault.

Security rules the resolver enforces

These are non-negotiable — the resolver refuses to run if any are violated:

exec.command may not contain whitespace or ;, |, &, <, >, $, `, \. If you need a pipeline, write a wrapper script and point command at it.
exec child processes get a minimal environment: PATH, plus only the variables listed in passEnv. Everything else is dropped.
anima refs require an active CLI auth context — the resolver prompts for login rather than falling through silently.
Resolved values never reach disk. They live in process memory for the duration of the child, then are overwritten.

Getting Started

Framework Toolkits

Platform

Agent Identity & A2A

Security

Compliance

Protocols

SDK Reference

Resources

Legal

Blog

SecretRef & anima.json

SecretRef & `anima.json`

The three sources

`anima` — Anima Vault

`env` — Environment variable

`exec` — Trusted binary

`anima.json` — putting it together

Using it

Why not just `.env`?

Security rules the resolver enforces

​SecretRef & anima.json

​The three sources

​anima — Anima Vault

​env — Environment variable

​exec — Trusted binary

​anima.json — putting it together

​Using it

​Why not just .env?

​Security rules the resolver enforces

SecretRef & `anima.json`

The three sources

`anima` — Anima Vault

`env` — Environment variable

`exec` — Trusted binary

`anima.json` — putting it together

Using it

Why not just `.env`?

Security rules the resolver enforces