DocsSettings

Use sandboxes

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:

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:

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 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 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:

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. The repo is cloned once; after that it’s an ordinary directory, saved with the disk and copied to forks. 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 contain the files. Anything that runs in the sandbox, including an agent, can read them. For AI provider keys, use cloudex keys instead: those never enter the sandbox.

For agents and LLMs: this page as Markdown,llms.txt and all docs in one file.