# Variables, files and repos

> Give a sandbox environment variables and files at every start, and a repo cloned when it's created, with cloudex new, cloudex env and the SDKs. GitHub tokens let git and gh work with private repos.

A sandbox's settings are environment variables and files it gets at every start, and a repo cloned into it when it's created. Set them when you make the sandbox:

```sh
cloudex new --name web \
  --repo https://github.com/you/app \
  --env GH_TOKEN=$(gh auth token) \
  --env-file .env \
  --file .npmrc=$HOME/.npmrc
```

Then change them on a running or stopped sandbox:

```sh
cloudex env                                   # names, files and the repo
cloudex env set DATABASE_URL=postgres://...   # the current sandbox
cloudex env set web --env-file .env.test
cloudex env unset web DATABASE_URL --file .npmrc
```

The [SDKs](https://cloudex.build/docs/sdk.md) take the same settings in `create()`, and change them with `updateSettings()`.

## Environment variables

Every shell, ssh session, `cloudex exec`, agent and desktop terminal in the sandbox gets them. Values can hold anything, including spaces, quotes, `#` and newlines.

| Flag | Effect |
|---|---|
| `--env NAME=VALUE` | One variable. Repeat it for more. |
| `--env-file PATH` | `NAME=VALUE` lines from a `.env` file. Lines starting with `#` are skipped, `export ` is allowed, and quotes around a whole value are removed. |

Names are letters, digits and underscores, not starting with a digit. `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `PWD` and names starting with `CLOUDEX_` are reserved; set `PATH` in `~/.profile` instead. A sandbox can have up to 100 variables.

A variable you set wins over a [provider key](https://cloudex.build/docs/keys.md) placeholder: `ANTHROPIC_API_KEY` in the settings is used as is, and goes to the provider unchanged.

## Files

`--file DEST=SRC` copies the file `SRC` from your computer to `DEST` in the sandbox's home directory: `.npmrc`, `~/.npmrc` and `/home/cloudex/.npmrc` are the same place. The CLI turns a `DEST` your shell expanded, such as `/Users/you/.npmrc`, back into `~/.npmrc`. Files are written as the `cloudex` user, readable only by it, and their directories are created as needed.

They're written again at every start, so an edit made inside the sandbox lasts until the next one. A file removed from the settings is deleted from the sandbox. A sandbox can have up to 20 files, and variables and files together can take up to 1 MB.

## Repos

`--repo URL` clones a repo into the home directory when the sandbox is created, into a directory named after the repo. Add `#branch` to the URL to check out a branch or tag:

```sh
cloudex new --repo https://github.com/you/app#dev
```

The SDKs and the API also take `{ url, dir, branch }`, to choose the directory. Only `https://` URLs work, and a URL with a user name or token in it is refused, because Cloudex shows the URL as is. For a private repo, set `GH_TOKEN`; see [GitHub](#github). The repo is cloned once; after that it's an ordinary directory, saved with the disk and copied to [forks](https://cloudex.build/docs/forks.md). If the clone fails, the sandbox starts anyway, with the reason in its `notice` (`cloudex info` shows it).

## GitHub

With `GH_TOKEN` or `GITHUB_TOKEN` among a sandbox's variables:

- `git` uses it for `https://github.com`, so cloning a private repo, and pushing, work without a login. That includes `--repo` when the sandbox is created.
- `gh`, the GitHub CLI, uses it too, so an agent can open a pull request.

A fine-grained token limited to the repos the sandbox needs is the safer choice: anything in the sandbox can read the variable.

## When changes take effect

`cloudex env set` and `unset` change a running sandbox at once. New shells, `exec` calls and agent turns see the change; programs already running keep the variables they started with, until they're restarted. That includes an agent session that `cloudex prompt` started: its tmux server started with the old values. A stopped sandbox gets the change when it next starts.

Forks get a copy of the original's settings, then change separately.

## Where they're kept

The deployment keeps each sandbox's variables and files in its Durable Object, encrypted under a key derived from the admin key. `cloudex env` and the API show only names and paths; nothing returns values or contents. After `cloudex deploy --yes` replaces the admin key, the settings can't be read: the sandbox starts without them, with a notice, and the next `cloudex env set` starts over.

Inside the sandbox, variables live in `/etc/cloudex/env.sh` and files in the home directory, so saves contain them like any file, and [backups](https://cloudex.build/docs/sandboxes.md#backups) contain the files. Anything that runs in the sandbox, including an agent, can read them. For AI provider keys, use [`cloudex keys`](https://cloudex.build/docs/keys.md) instead: those never enter the sandbox.
