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

# Managing your agent's secrets

> Set, inspect, and rotate encrypted agent secrets via the CLI or API.

Secrets are scoped to an agent or shared vault-wide, stored AES-256-GCM encrypted, and decrypted into the container environment at deploy time. See [secret management overview](/platform/secret-manager/overview) for the encryption model.

<Note>
  This is separate from your project's local `.env` (used only by `nasiko run .`) and from the
  control plane's own environment (used by the routing engine and orchestrator chat) — the same
  key commonly needs to be set in all three places for different parts of the platform to work.
  See the [quickstart prerequisites](/quickstart#prerequisites) for the full breakdown.
</Note>

## CLI

```bash theme={null}
# Scoped to one agent
nasiko secrets set STRIPE_API_KEY sk_live_xxxxx --agent my-billing-agent

# Vault-wide — available to any agent you deploy
nasiko secrets set OPENAI_API_KEY sk-xxxxx

# List names (values are never echoed back)
nasiko secrets ls --agent my-billing-agent

# Read metadata
nasiko secrets get STRIPE_API_KEY --agent my-billing-agent

# Remove
nasiko secrets rm STRIPE_API_KEY --agent my-billing-agent
```

Without `--agent`, a secret lives at the vault level and any agent you deploy can reference it.

## API

The same operations are split across two route families, not one:

| Scope      | Routes                                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Vault-wide | `GET`/`POST /api/secrets`, `GET`/`PUT`/`DELETE /api/secrets/{name}`                                                                       |
| Per-agent  | `GET`/`POST /api/agents/{agent_id}/secrets`, `POST /api/agents/{agent_id}/secrets/import`, `DELETE /api/agents/{agent_id}/secrets/{name}` |

Both are authenticated the same way.

## Who can manage secrets

Setting, reading, or removing secrets requires the `can_manage_secrets` permission. See [access control](/onboarding/acl/overview).

## How secrets reach a running agent

Secrets aren't mounted as files or fetched at runtime. They're decrypted server-side and injected as environment variables at deploy time, alongside the observability configuration. To the agent, a secret is just an environment variable that's there at process start.

<Warning>
  Changing a secret's value doesn't affect an already-running container. Run `nasiko restart` to re-read the current secret set and re-inject it.
</Warning>

## Refresh on scale-up

When an agent scales up, Nasiko refreshes secrets immediately before new replicas start, so every replica runs current values. Scaling up is itself a refresh point — no manual restart needed after rotating and then scaling.

## Related

* [Secret management overview](/platform/secret-manager/overview) — encryption at rest
* [Access control overview](/onboarding/acl/overview) — role requirements
* [Agent runtime](/platform/agent-registry) — the deploy and lifecycle flow