> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amika.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables vs. secrets

> When to use a plain environment variable and when to use a vault-backed secret.

Every value you inject into a sandbox is one of two things: a **plain
environment variable** or a **vault-backed secret**. This page explains the
decision so you can pick the right one, then points you to the guides that cover
each in depth.

## The decision

You declare both in the `[env]` table of `.amika/config.toml`. The difference is
whether the value itself lives in the repo or in the Amika vault.

```toml theme={null}
[env]
# Plain environment variable — the literal value is committed in the repo
NODE_ENV = "production"
DATABASE_HOST = "db.internal"

# Secret — a reference by name; the value lives in the Amika vault
ANTHROPIC_API_KEY = { secret = "my-anthropic-key" }
```

|                           | Plain environment variable                                        | Secret                                                 |
| ------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
| **Syntax**                | `KEY = "value"`                                                   | `KEY = { secret = "name" }`                            |
| **Where the value lives** | In `.amika/config.toml`, committed to the repo                    | In the Amika vault, referenced by name                 |
| **Use for**               | Non-sensitive config: hostnames, ports, feature flags, `NODE_ENV` | Anything sensitive: API keys, tokens, passwords        |
| **Set up before create**  | Nothing — the value is in the file                                | Push the secret with `amika secret push` or the web UI |

The rule of thumb: if you would be uncomfortable seeing the value in your Git
history, make it a secret. Otherwise a plain value is simpler and versioned with
your code.

## Security model today

<Warning>
  Secrets are resolved at sandbox creation time and **copied into the sandbox VM**,
  where they are readable as environment variables from inside the sandbox. The
  vault protects secrets at rest and keeps them out of your repository — it does
  not currently isolate them from code running in the sandbox.
</Warning>

A future design (tokenized secrets swapped in by a network proxy on outbound
requests, so the agent never sees real values) is described under
[Secrets Vault](/architecture/roadmap#secrets-vault) in the roadmap. Until that
ships, treat any secret injected into a sandbox as visible to the agent and any
code it runs.

## Where to go next

* [Manage secrets](/guides/manage-secrets) — push, list, and update vault secrets, including Claude and Codex credentials.
* [Inject credentials](/guides/inject-credentials) — wire stored secrets and agent credentials into a sandbox at create time.
* [config.toml reference](/guides/config-toml#env) — the full `[env]` syntax, including service references.