| name | animus-configuration |
| description | Animus project config, daemon config, plugin config, agent runtime, environment variables, and state layout |
| user_invocable | false |
| auto_invoke | true |
| animus_version | 0.7.0-rc.18 |
Configuration
Animus resolves behavior from the project manifest animus.toml,
project-local .animus/, installed packs, repo-scoped runtime state under
~/.animus/<repo-scope>/, global machine config, environment variables, and
installed STDIO plugins.
Project-local sources
animus.toml (v0.6.9+) — the project manifest
Committed at the repo root; scaffolded by animus init. Declares intent:
[project] (kernel version), [plugins], and [packs], with each
dependency as a version string, { git, tag }, or { path }.
animus install resolves it into .animus/plugins.lock and installs the
set; animus install --locked (CI/Docker) reproduces the committed lock
exactly and fails on manifest↔lock drift; animus add <spec> /
animus remove <name> mutate the manifest and install/uninstall. Team
onboarding is git clone && animus install.
animus init also scaffolds .env.example and a merge-safe project
.gitignore. animus install syncs .env into the device-encrypted secret
store (idempotent; blank KEY= values are skipped, never stored empty;
imports audited) and warns about keys declared in .env.example but unset.
.animus/config.json
Repository-local config created by animus init. It holds only the
optional auto_update block (self-update mode/interval/channel) and optional
CLI settings such as default_subject_kind and a project mcp_servers map.
It carries no daemon runtime settings — those live in the repo-scoped
~/.animus/<repo-scope>/daemon/pm-config.json, written by
animus daemon config.
.animus/workflows.yaml and .animus/workflows/*.yaml
Hand-authored workflow sources. Typical uses:
- Define repo-specific workflow ids and the default workflow.
- Declare project MCP servers, agents, variables, phases, and workflows.
- Configure agent memory and communication channels.
- Declare top-level
schedules: (cron dispatch, UTC) and triggers:
(event dispatch from watchers, webhooks, or trigger plugins).
- Set
worktree: mode (auto default / required / skip) per
workflow or phase.
- Map logical secret names in
secrets:, referenced as ${secret.<name>}
and resolved at consume/spawn time since v0.6 (env first, then the
animus secret keychain store) — the reference passes through config
parsing verbatim; resolved values never land in compiled artifacts.
- Declare v0.7 execution-environment surfaces:
workspaces:,
environment_routing:, and workflow/phase environment: /
workspace: fields.
Use:
animus workflow config get
animus workflow config validate
animus workflow config compile
validate / compile also report declared-but-unenforced fields and
unresolvable explicit skills: names in a warnings array.
Config sourcing is a plugin since v0.6.0: the kernel no longer parses
.animus/*.yaml in the runtime load path — the base WorkflowConfig comes
exclusively from an installed config_source plugin. The default
launchapp-dev/animus-config-yaml serves exactly these YAML files (so YAML
remains the default authoring surface); the portal uses the consolidated
animus-postgres plugin instead. The daemon requires the role at preflight
and keeps ONE resident config_source host per project root (re-spawned only
on process death or binary mtime change, with a CacheToken short-circuit
when the source config is unchanged), so file edits are picked up without
per-load process churn. A malformed edit keeps the prior config active and
broadcasts config_reload_failed instead of crashing. Manual trigger:
animus workflow config reload. Daemon transport settings and
.animus/plugins.lock changes still require a daemon restart.
Sources that advertise config_write also accept CLI write-back:
animus workflow config set / agent-set / agent-remove / workflow-set / workflow-remove / phase-set (rc.13+) edit the base config without touching
YAML by hand.
.animus/skills/<name>/SKILL.md
Project-scoped Markdown skills (highest priority in skill resolution).
YAML skill definitions live at .animus/config/skill_definitions/<name>.yaml.
Agent-host skills from .claude/skills and .codex/skills are lower-trust
prompt-text-only probes.
.animus/plugins/, .animus/plugins.lock, .animus/plugins.yaml
Project-scoped plugin triple, populated by animus install (from
animus.toml) or animus plugin install --project (same flag on
uninstall / update): binaries in .animus/plugins/, the lockfile
.animus/plugins.lock, and a registry .animus/plugins.yaml.
The lock is the source of truth (v0.6.9+): plugins.yaml is a derived
projection regenerated from the lock on every mutating op — never hand-edit
it, and don't treat it as authoritative; drift heals on the next operation.
Lock schema 2.0 (v0.6.7) records per-target-triple integrity
(targets: {triple → {archive_sha256, signature_bundle_sha256, installed_binary_sha256}}) for every published platform, so a lock generated
on macOS drives a verified --locked install in a linux container.
Project installs run the identical integrity pipeline as global installs
(sha256, cosign policy, publisher TOFU, fail-closed lockfile) and shadow
same-named global installs during discovery (animus plugin list shows a
SCOPE column and a shadowed array). Commit animus.toml and
.animus/plugins.lock (animus plugin lock verify sweeps both global and
project roots); never commit binaries — animus init and project installs
write a .animus/.gitignore covering plugins/.
.animus/plugins/<pack-id>/ doubles as the project-local pack override root.
.animus/plugin-scope.yaml
Limits which installed plugins this project loads. mode: is all
(default), flavor-only (plugins declared by the active flavor), or
allowlist (names under allow:); extras: layers additions. Manage with
animus plugin scope {show,set,reset}. The file also persists the project's
active flavor under active_flavor:, written by a successful
animus plugin install-defaults --flavor <name> / animus flavor install <name> (selecting default clears the key). animus flavor current reads
it back and reports the source (flag / persisted / default).
Repo-scoped runtime state
Mutable project runtime state lives outside the repo:
~/.animus/<repo-scope>/
├── core-state.json
├── cost-state.v1.json
├── decisions.jsonl
├── budget-enforcement.v1.json
├── resume-config.json
├── workflow.db
├── .journal-imported-v1 # marker: one-time SQLite→journal-plugin import done
├── config/
│ ├── state-machines.v1.json
│ └── agent-runtime-config.v2.json
├── daemon/
│ ├── daemon.log
│ └── pm-config.json
├── interactions/
├── logs/
│ └── events.jsonl
├── mcp-oauth-cache/
│ └── <server>.json
├── runs/<run-id>/
├── artifacts/<run-id>/
├── state/
│ └── pack-selection.v1.json
├── workflow-environments/ # v0.7: environment-broker lease records (<run_id>.json)
└── worktrees/
Key files:
workflow.db stores persisted workflows, tasks, requirements, and checkpoints.daemon/pm-config.json stores persisted daemon runtime settings
(including the notification_config block); daemon/daemon.log is the
detached daemon's process log.cost-state.v1.json stores per-workflow/per-phase token + USD rollups;
budget-breach decisions append to decisions.jsonl;
budget-enforcement.v1.json records the enforcement sweep's
{enabled, last_sweep_at} status surfaced by animus daemon health.config/agent-runtime-config.v2.json is the compiled agent runtime config
(which AI model/tool each agent profile uses); inspect/validate/replace it
via animus workflow agent-runtime get|validate|set rather than editing
the file. The compiled workflow config (animus.workflow-config.v2) is
in-memory only — an on-disk config/workflow-config.v2.json is a hard
load error, not a cache.workflow-environments/<run_id>.json (v0.7) are durable environment-broker
leases for runs pinned to an execution environment; stale leases are
cold-torn-down by the daemon's startup reaper.interactions/ stores pending agent questions/approvals
(animus agent interactions).mcp-oauth-cache/<server>.json caches resolved OAuth tokens for
HTTP MCP servers (0600 on Unix).runs/<run-id>/ and artifacts/<run-id>/ are never auto-deleted —
reclaim disk with animus workflow prune / animus workflow delete.
Treat these as Animus-managed state. Prefer CLI or MCP tools over direct edits.
Daemon config
Read current settings:
animus daemon config
MCP: animus.daemon.config
Update runtime settings (written to daemon/pm-config.json):
animus daemon config --pool-size 3
animus daemon config --max-tasks-per-tick 2 --stale-threshold-hours 12
animus daemon config --phase-timeout-secs 3600
animus daemon config --max-daily-usd 50 --silent-threshold-mins 20
Fleet knobs: --max-daily-usd is a rolling-24h fleet cost cap (pass 0 to
clear); --silent-threshold-mins (default 20) bounds how long a run may go
without output before it is flagged. There is no --auto-run-ready knob.
MCP: animus.daemon.config-set
The running daemon re-reads these keys once per scheduler tick, so changes
apply without a restart (exception: a changed phase_timeout_secs only
reaches the live process manager after a restart).
Removed knobs: the daemon git/merge policy (auto_merge, auto_pr,
auto_commit_before_merge, auto_prune_worktrees) and the no-op
idle_timeout_secs were deleted in v0.5.13 — old pm-config.json files
still load. Git automation (commit / push / PR / merge) is now expressed as
command: phases running git / gh in the workflow; the
post_success.merge and integrations.git.auto_merge keys were removed and
now fail to parse.
Daemon lifecycle
animus daemon preflight
animus daemon start
animus daemon start --auto-install
animus daemon run
animus daemon restart
--autonomous was removed — daemon start now errors on it as an unknown
argument; detached is the only daemon start behavior. Starting while
already running is idempotent.
Scheduler wake model
The daemon main loop is event-driven, not polling. A dispatch pass runs on:
daemon/nudge control messages (sent fire-and-forget by
animus subject create/update/status and animus queue enqueue/release
and their MCP equivalents — pickup is typically sub-second), precise cron
deadlines from compiled schedules: (with a 10-minute catch-up horizon),
and workflow/phase completions. interval_secs (default 5) is only the
fallback heartbeat: it bounds pickup of out-of-band state edits and
paces the heavier housekeeping sweeps. Concurrency knobs: pool_size caps
steady-state concurrent runners (upper-bounded by
ANIMUS_WORKFLOW_CONCURRENCY_MAX, default 10); max_tasks_per_tick
(default 2) caps new dispatches per pass. See
docs/reference/configuration.md#scheduler-wake-model.
Notifications
Notification dispatch is configured via the notification_config block
persisted in daemon/pm-config.json. Webhook URLs and headers reference
env var names through url_env / headers_env fields — commonly
ANIMUS_NOTIFY_WEBHOOK_URL and ANIMUS_NOTIFY_BEARER_TOKEN — and only
those named vars are forwarded to the notifier plugin. Notifier events
include workflow-failed, task-blocked, and workflow-budget-breach.
Machine-wide config
~/.animus/
├── config.json # global user config, telemetry consent, claude profiles
├── auto-update-state.json
├── credentials.json
├── principals.yaml
├── trusted-orgs.yaml # plugin-install TOFU allowlist (audited; revoke-trust)
├── trusted-signers.yaml
├── plugins.lock / plugins.yaml # global lockfile (source of truth) + derived registry
├── plugins/<plugin-name>
├── packs/<pack-id>/<version>/
├── skills/<skill-name>/SKILL.md
├── cache/manifests/ # plugin manifest cache (animus plugin cache)
└── template-registries/
Principals and RBAC
~/.animus/principals.yaml (hand-editable) declares principals, roles,
and policy.rbac: single-user (default; checks skipped) or enforce
(requests must resolve to a declared principal). Inspect identity with
animus auth whoami; --as <principal> is honor-system under
single-user and credential-checked under enforce.
Packs
animus pack list
animus pack info --pack-id animus.task
animus pack install --path /tmp/vendor.pack --activate
animus pack pin --pack-id vendor.pack --version =1.2.3
pack install also resolves declared pack dependencies (--no-deps skips,
--dry-run previews) and checks [[requires_plugins]] against the
installed-plugin registry (--install-plugins installs missing ones).
The pack inspect alias was retired in v0.5.14 — use pack info.
Plugins and flavors
animus install
animus install --locked
animus add launchapp-dev/animus-subject-linear@v0.2.0
animus remove animus-subject-linear
animus plugin install-defaults
animus plugin install-defaults --include-recommended
animus plugin list
animus plugin outdated
animus plugin lock verify
animus flavor current
animus web serve and animus web open require installed transport/UI
plugins (animus plugin install-defaults --include-transports).
Self-update / avm
animus update self-updates plain installs (~/.local/bin,
/usr/local/bin, Cargo) with --check, --yes, --channel stable|nightly,
--force, --prerelease. When the running binary is managed by avm (the
Animus Version Manager — kernels under ~/.avm/versions/, dispatched through
an animus shim), animus update defers: it prints the avm install /
avm use commands and exits instead of self-replacing (v0.6.11). Multi-project
machines should prefer avm. The former animus self update group was retired
— no aliases. Background checks are governed by the auto_update block in
.animus/config.json or ~/.animus/config.json
(mode: off|notify|prompt|auto).
Telemetry
Opt-in anonymous metrics live under animus daemon metrics {status,enable,disable,flush,cleanup} (the top-level animus metrics group
was removed in v0.5.14). Bare animus daemon metrics is the live
counters/gauges display and degrades gracefully when the daemon is offline
(exits 0 with telemetry status; only --watch requires a live daemon).
Consent persists in the user-global ~/.animus/config.json;
ANIMUS_METRICS_DISABLE=1 is the hard kill switch.
Environment variables
Core variables:
| Variable | Purpose |
|---|
ANIMUS_CONFIG_DIR | Override global config root, default ~/.animus |
ANIMUS_DISABLE_CI_CACHE / ANIMUS_CI_CACHE_TTL_SECS | Disable / tune the animus status CI-status cache |
ANIMUS_MCP_SCHEMA_DRAFT | Select Draft-07 MCP schemas |
ANIMUS_MCP_ENDPOINT | Override embedded MCP client endpoint |
ANIMUS_USER_ID / ANIMUS_ASSIGNEE_USER_ID | Override recorded user / assignee ids |
ANIMUS_DEBUG | Enable verbose debug logging |
ANIMUS_LOG_JSON | Emit JSON logs |
ANIMUS_DEBUG_MCP_STDIO | Log raw MCP stdio frames |
ANIMUS_AUTO_UPDATE_MODE / ANIMUS_AUTO_UPDATE_DISABLE | Override / short-circuit self-update behavior |
ANIMUS_METRICS_DISABLE | Hard kill switch for opt-in telemetry |
Plugin and template variables:
| Variable | Purpose |
|---|
ANIMUS_PLUGIN_DIR | Override global plugin install directory |
ANIMUS_PLUGIN_PATH | Extra directories scanned for plugin binaries |
ANIMUS_PLUGIN_SIGNATURE_POLICY | Signature policy override: strict / warn / skip (precedence: per-call flag > this env > global config > warn) |
ANIMUS_SERVER=1 | Server mode: fail-closed org TOFU — --yes/--force never auto-trust an unknown org (use --allow-org) |
ANIMUS_DISABLE_MANIFEST_CACHE / ANIMUS_CACHE_DIR | Bypass / relocate the plugin manifest cache |
ANIMUS_RESIDENT_HOST_CACHE_MAX | Cap the resident plugin-host registry (legacy ANIMUS_SUBJECT_HOST_CACHE_MAX still read) |
ANIMUS_FLAVORS_DIR | Override the flavors/<name>.toml probe directory |
ANIMUS_TEMPLATE_REGISTRY_URL | Override project-template registry |
Environment / journal variables (v0.7):
| Variable | Purpose |
|---|
ANIMUS_ENVIRONMENT_DELEGATE | Gate: delegate worktree materialization to the resolved environment plugin (default off) |
ANIMUS_ENVIRONMENT_EXEC | Gate: route agent exec through resolved environment plugins (default off; no silent local fallback once resolved) |
ANIMUS_ENVIRONMENT_BROKER_* | Daemon-set on runners: private broker socket/bearer for exec proxying — not user-set |
ANIMUS_DAEMON_DISABLE_JOURNAL_RESUME | Kill-switch: skip the boot reconcile that RESUMES in-flight runs from a durable workflow_journal after restart |
ANIMUS_MCP_OAUTH_CACHE_DIR | Relocate the MCP OAuth token cache (containerized/durable-volume deployments) |
Workflow-runner variables:
| Variable | Purpose |
|---|
ANIMUS_WORKFLOW_RUNNER_BIN | Override the workflow-runner binary path |
ANIMUS_PHASE_RUN_ATTEMPTS / ANIMUS_PHASE_MAX_CONTINUATIONS | Phase retry / continuation caps |
ANIMUS_MCP_WORKFLOW_ID | Pin animus mcp serve to a workflow (suspend-mode interactions) |
Daemon runtime quotas (read once at daemon startup; 0/empty falls back to default):
| Variable | Default | Purpose |
|---|
ANIMUS_TRIGGER_BACKLOG_MAX | 1000 | Max unprocessed trigger events retained per trigger |
ANIMUS_SUBSCRIBER_MEMORY_MAX_MB | 10 | Per-subscriber buffer cap for workflow/events |
ANIMUS_PLUGIN_PROCESS_MAX | 50 | Max concurrent plugin child processes |
ANIMUS_WORKFLOW_CONCURRENCY_MAX | 10 | Max parallel workflow runners; also upper-bounds pool_size |
Provider passthrough examples:
| Variable | Purpose |
|---|
ANIMUS_CLAUDE_EXTRA_ARGS / _JSON | Extra Claude CLI args |
ANIMUS_CLAUDE_BYPASS_PERMISSIONS | Skip Claude permission prompts (unattended test envs only) |
ANIMUS_CODEX_EXTRA_ARGS / _JSON | Extra Codex CLI args |
ANIMUS_CODEX_EXTRA_CONFIG_OVERRIDES / _JSON | Extra Codex --config overrides |
ANIMUS_CODEX_NETWORK_ACCESS / ANIMUS_CODEX_WEB_SEARCH | Toggle Codex sandbox network / web search |
ANIMUS_GEMINI_EXTRA_ARGS / ANIMUS_OPENCODE_EXTRA_ARGS (+ _JSON) | Extra Gemini / OpenCode CLI args |
Removed in v0.5.13: ANIMUS_RUNNER_CONFIG_DIR, ANIMUS_RUNNER_SCOPE, and
the --runner-scope flag (dead since the agent-runner sidecar deletion).
Plugin kill-switches
Operator escape hatches; all require a daemon restart to take effect (and
another to re-enable):
| Variable | Effect |
|---|
ANIMUS_DAEMON_DISABLE_TRIGGERS=1 | Skip the trigger plugin supervisor (also interrupts in-progress restart backoff) |
ANIMUS_DAEMON_DISABLE_SUBJECT_PLUGINS=1 | Skip subject plugin discovery entirely |
ANIMUS_DAEMON_DISABLE_LOG_STORAGE_PLUGIN=1 | Ignore log_storage plugins; use in-tree logs/events.jsonl |
ANIMUS_DAEMON_DISABLE_BUDGET_ENFORCEMENT=1 | Skip the budget-cap enforcement sweep (no auto-pause/fail; sweeps still record disabled status for daemon health / status) |
ANIMUS_PROVIDER_DISABLE_PLUGIN was removed in v0.4.12 — uninstall or
quarantine a misbehaving provider plugin instead.
Secret handling
Do not put API tokens in workflow YAML. Preferred: store secrets in the OS
keychain with animus secret set <KEY> (also get, list, rm,
import-env, export-env). Plugins and the ${VAR} interpolator resolve
explicit parent-process env first, then the keychain entry for the current
repo-scope. The daemon does not auto-load .env files — source them before
startup, or migrate with animus secret import-env.
Use YAML interpolation for non-secret config only:
subjects:
- id: my-linear
backend: linear
config:
team_id: ${LINEAR_TEAM_ID:-default-team}
workspace: ${LINEAR_WORKSPACE:?set LINEAR_WORKSPACE}
${VAR} errors with file path + line number when unset; ${VAR:-default}
falls back; ${VAR:?message} customizes the error; $$ escapes a literal
$. ${...} inside YAML comments is not interpolated (fixed in v0.5.13).
For credentials a phase or MCP server must receive, declare a secrets:
block and reference ${secret.<name>} — since v0.6 the reference passes
through config parsing verbatim and is resolved at consume/spawn time (env
first, then keychain); resolved values are kept out of compiled artifacts,
generated overlays, and parse diagnostics.
HTTP-transport mcp_servers entries can attach an oauth: block; the daemon
resolves a bearer token and injects the Authorization header. Credentials
are read from env vars named via *_env pointers (never inline in YAML), and
tokens are cached at ~/.animus/<repo-scope>/mcp-oauth-cache/<server>.json.
Authenticate with animus mcp auth <server>; check animus mcp auth-status.
Cost and budget governance
Declared workflow budget: caps are enforced by the daemon's housekeeping
sweep once per heartbeat: a newly crossed cap triggers the declared
on_exceed action (pause / fail / warn), a breach record, and one
workflow-budget-breach notifier event. Inspect spend with
animus cost {summary,workflow,top,trends,conversation,decisions}
(--by provider|model|task grouping). With no daemon running, animus cost
records breaches but never pauses anything.
Precedence
Workflow resolution:
- CLI flags and
--input-json / --var overrides
- Supported environment variables
- Project pack overrides in
.animus/plugins/
- Project YAML in
.animus/workflows.yaml and .animus/workflows/*.yaml
- Installed packs in
~/.animus/packs/
Skill resolution:
- Project
.animus/skills/ and .animus/config/skill_definitions/
- User
~/.animus/skills/
- Installed registry or pack skills, including
animus.core-skills
- Agent-host probes such as
.claude/skills or .codex/skills as prompt-text-only
