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

# Env vars & secrets

> Set environment variables and secrets once. boxd injects them into every machine you own.

Set environment variables and secrets **once**, at the organization level, and boxd injects them into every machine you own. This means into login shells, into the environment your `boxd machine exec` commands and coding agents run in, and into services your machine starts at boot. Every machine picks the values up on its own, without `.env` files to copy around.

There are two kinds:

|               | `boxd env`                | `boxd env … --secret`                         |
| ------------- | ------------------------- | --------------------------------------------- |
| For           | non-sensitive config      | tokens, API keys, passwords                   |
| At rest       | cleartext                 | **sealed**                                    |
| Readable back | yes (`list` shows values) | **never** (`list` shows names and scope only) |

Both are injected into your machines the same way. The difference is what happens at rest. Env var values are stored in cleartext and shown by `list`. Secret values are sealed and never returned by the API, not even to you. To change a secret you re-`set` it.

Manage them from the [CLI](/cli/commands), the in-VM CLI, or the console.

## Environment variables

```bash theme={"theme":"github-dark"}
boxd env set DATABASE_URL postgres://user:pass@db.example.com/app   # create or update
boxd env list                                                       # list, values shown (alias: ls)
boxd env rm DATABASE_URL                                            # remove (alias: remove)
```

## Secrets

```bash theme={"theme":"github-dark"}
boxd env set OPENAI_API_KEY sk-... --secret   # create or rotate (sealed at rest)
boxd env list                                 # secrets print as (sealed), never the value (alias: ls)
boxd env rm OPENAI_API_KEY --secret           # remove (alias: remove)
boxd env scope OPENAI_API_KEY private         # move a secret to a different scope (value preserved)
```

## Naming

Names must be valid environment identifiers, made of letters, digits, and underscores, starting with a letter or an underscore. The `BOXD_*` prefix is reserved for boxd's own variables.

## Scope

The `--scope` flag decides which of the org's machines receive the variable:

| Scope     | Applies to                             |
| --------- | -------------------------------------- |
| `shared`  | shared org machines only (**default**) |
| `private` | your private, org-billed machines only |
| `all`     | both                                   |

```bash theme={"theme":"github-dark"}
boxd env set API_BASE https://api.internal --scope all
boxd env set DEPLOY_KEY ... --scope private --secret
```

## How they reach a machine

On boot, and again on every login shell, boxd resolves the env vars and secrets in scope for that machine and exports them. So they're present for:

* interactive shells (`ssh <vm>.boxd`),
* `boxd machine exec` commands,
* the pre-installed coding agents, and
* services your machine starts at boot.

Add or rotate a value and new machines pick it up immediately. Already-running machines see it on their next boot profile refresh.