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

# Secrets

> Let templates require API keys without ever storing them.

A template often needs credentials: an Anthropic key, a database URL, an OAuth token. Secrets let a template **declare** what it needs without ever containing the value. The launching user supplies it from their vault, and Orgo injects it into the computer at create time. The value never lives in the template, the registry, or the golden snapshot.

## Existing computers

In Settings → Credentials, save the value in the Secrets section, then choose **Apply** and select a running Linux computer. The [Apply secrets endpoint](/api-reference/computers/sync-secrets) provides the same action for API clients.

Workspace values override account values with the same name. Open a new terminal or restart the agent afterward; running programs keep their previous environment. Updating the vault alone does not modify an existing computer, and deleting a vault entry does not remove copies already installed there.

## The model

<Steps>
  <Step title="Declare">
    The template lists the secrets it needs under `secrets`. Names only, no values.
  </Step>

  <Step title="Supply">
    The launching user stores the value in their vault (once, per account).
  </Step>

  <Step title="Inject">
    At create, Orgo writes the user's matching secrets into the computer at `/root/.env` (mode `0600`). They are never baked into the shared snapshot.
  </Step>
</Steps>

## Declare

```yaml theme={null}
secrets:
  - name: anthropic_api_key       # lowercase; maps to the ANTHROPIC_API_KEY vault entry
    description: Anthropic API key, used by Claude Code.
    example: "sk-ant-..."
    docs_url: https://console.anthropic.com/settings/keys
    optional: true                # template still launches when absent
```

| Field | Description |
| - | - |
| `name` | Lowercase, alphanumeric with `-` or `_`. Orgo maps it to its `UPPER_SNAKE_CASE` form (e.g. `ANTHROPIC_API_KEY`) and looks that name up in your vault. **Required.** |
| `description` | Shown to the launching user. |
| `example` | Example value shape, e.g. `sk-ant-...`. |
| `docs_url` | Where to obtain the secret. |
| `optional` | Marks the secret as one the template works without. Defaults to `false`. It is informational: the [CLI](/guides/cli) labels each secret optional or required and names the required ones when you launch, but a launch never fails over a missing secret. |

## Reference

At launch, Orgo writes each declared secret you have set to `/root/.env` under its `UPPER_SNAKE_CASE` name, so `anthropic_api_key` becomes `ANTHROPIC_API_KEY`. New interactive shells source `/root/.env`, so terminals see the variable.

You can also name a declared secret in `env` with `{secret: <name>}`:

```yaml theme={null}
secrets:
  - name: anthropic_api_key

env:
  ANTHROPIC_API_KEY:
    secret: anthropic_api_key
```

<Warning>
  When Orgo launches a built template, it does not apply `env` secret references or `secret://` files. The value arrives only under the secret's own `UPPER_SNAKE_CASE` name, so an `env` key receives it only when the key is that name, as above. A file with `from: secret://<name>` passes validation but is never written.
</Warning>

Only declared secrets you have set are injected. A launch never fails over a missing secret, whether or not it is `optional`: the variable is simply absent.

## Secrets and golden snapshots

A template computer starts from the **golden snapshot**, which was built *before any particular user launched it*. The user's secret is injected per computer at create, after the snapshot was baked.

So a launch that injects secrets does not restore the snapshot's memory. It cold-boots from the snapshot's disk with `/root/.env` already written, and `/root/.env` is sourced before app services, terminal sessions, and the `on_every_boot` hook start, so all of them see the secret. A launch with no secrets to inject restores the snapshot's memory when its host can, with every process as the build left it.

On a launch that injects secrets, `/root/.env` holds only the secrets: literal `env` values the template wrote there are not set. Put a value a service needs in that service's own `env`.

To start a program with the launcher's key, give a [terminal](/guides/templates/schema#terminal) session a `run` command, or run the program as an [app service](/guides/templates/schema#apps):

```yaml theme={null}
secrets:
  - name: anthropic_api_key
    optional: true

terminal:
  - name: claude-code
    cwd: /root
    run: claude
```

This is the pattern the curated `system/coding` template uses: its `claude-code` and `codex` sessions run `claude` and `codex`. Do not rely on the `on_resume` hook for this, because launched computers do not run it.

## Managing your vault

Add and update secret values in the Secrets section of Settings → Credentials, at [orgo.ai/settings/credentials](https://www.orgo.ai/settings/credentials). A secret is either account-wide or scoped to one workspace. Store an account-wide key once and every template you launch can request it by name. A workspace value takes precedence over an account value with the same name.

From the [CLI](/guides/cli), `orgo secrets set ANTHROPIC_API_KEY` stores a value (it prompts for the value when you omit it) and `orgo secrets list` shows the names you have set.

## Security

* Values are **encrypted at rest** and never returned to a client in plaintext.
* A secret is **never** part of the template document, its `digest`, or the golden snapshot.
* Build logs never print secret values.
* Only secrets a template explicitly declares are injected, and only if you have them set.

## Next steps

<CardGroup cols={2}>
  <Card title="Schema reference" icon="file-code" href="/guides/templates/schema#env">
    `env`, `files`, and `secrets` in full.
  </Card>

  <Card title="Examples" icon="book-open" href="/guides/templates/examples">
    See a launch-time secret in a real template.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.