Environment & Secrets

The capsule subprocess runs in an isolated environment. By default it sees nothing from the host machine — no shell variables, no PATH, no credentials. What it sees is entirely determined by the agent's configuration. This is the right default: agents installed from the registry should not silently inherit access to your machine's environment.

You opt in to what the agent needs. Nothing more.

The .env file

Every agent folder has a .env file. This is the primary place to put secrets.

# ~/.axon/agents/my-agent/.env
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxx
DATABASE_URL=postgres://localhost:5432/mydb

Standard dotenv format. Parsed by Bun's native loader — quoted values, multiline values, and comments are all supported.

The .env file is:

• Never committed — .gitignored when axon init scaffolds the agent folder
• Never published — excluded from axon agent deploy and axon module deploy
• Agent-local — each agent has its own .env, isolated from every other agent
• Highest priority — if the same key appears in .env and in host passthrough, .env wins

Add secrets here. That's it.

Passthrough — host environment keys

For keys that live in your shell environment and you want the agent to inherit, declare them explicitly in axon.config.ts:

env: {
    passthrough: ["PATH", "HOME", "TERM", "ANTHROPIC_API_KEY"],
}

Only the keys you list are pulled through. Nothing else from the host environment reaches the capsule. This is intentional — when you install an agent from the registry and boot it, it cannot read your AWS_SECRET_ACCESS_KEY unless you explicitly added it to the passthrough list.

The default agent ships with ["PATH", "HOME", "TERM"] — the minimum needed to behave like a normal development environment.

cwdEnv — project-local secrets

When your agent is working inside a project that has its own .env file, you can load it alongside the agent's own:

env: {
    cwdEnv: true,
}

When cwdEnv is true, the runtime also loads .env from the capsule's current working directory. This is useful for coding agents that operate inside a repo — the project's own secrets are available without duplicating them into the agent's .env.

Resolution order

When the same key appears in multiple sources, priority is:

Agent .env always wins. You can pin a specific value there and it will override whatever is in the host environment or the project's .env.

needs and describe — advisory declarations

Agents and modules published to the registry can declare what keys they expect. This is advisory — it drives the install prompt, it does not enforce anything at runtime.

env: {
    needs: ["GITHUB_TOKEN", "LINEAR_API_KEY"],
    describe: {
        GITHUB_TOKEN:   "Open PRs and read repo state",
        LINEAR_API_KEY: "Read and update Linear issues",
    },
}

When someone installs this agent or module, they see:

dev-workflow needs these environment keys:
  • GITHUB_TOKEN   — Open PRs and read repo state
  • LINEAR_API_KEY — Read and update Linear issues

Add these to ~/.axon/agents/dev-workflow/.env after install.

Use needs and describe when publishing. It saves the person installing your agent from having to read your source code to figure out what secrets to add.

What the agent sees

The LLM is aware of which environment keys are available — key names are visible in the <capsule> context block injected into every prompt. Values are never visible: they do not travel over the runtime bridge, do not appear in prompt rendering, and never land in the JSONL session file.

The agent sees key names, not values. In the LLM's injected context block:

// <capsule>
//   <env>GITHUB_TOKEN, LINEAR_API_KEY, PATH, HOME</env>
//   ...
// </capsule>

This lets the agent reason about what services it can call — it knows GITHUB_TOKEN is present, so it can attempt GitHub API calls — without the values ever being exposed.

Rotating secrets

Update the value in .env and save. In local development, Axon reloads the capsule so future tool calls see the new environment without reopening the TUI. The values still stay inside the capsule; only key names are surfaced to the model.

Once env is configured, Policy defines what the capsule can actually do with those credentials.