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:
gituses it forhttps://github.com, so cloning a private repo, and pushing, work without a login. That includes--repowhen 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.