Use sandboxes
Commands, files and CI
Run commands with their output as it comes, leave long jobs and servers running in the background, copy files in and out with cloudex cp, and run CI jobs in a fresh sandbox with cloudex run.
Four commands cover scripts, CI jobs and agents that drive a sandbox from outside:
cloudex exec -- npm test # run a command; output as it comes
cloudex exec -d -- npm run dev # leave one running in the background
cloudex cp ./data :data # copy files in, or out
cloudex run -- npm test # a fresh sandbox with this directory, then gone
The API and the SDKs do the same.
Run a command
cloudex exec -- npm test
cloudex exec web -- 'cd app && git status'
cloudex exec -- python3 -c 'print(42)'
cloudex exec --root -- apt-get install -y ripgrep
cloudex exec --cwd app --timeout 30m -- make
cloudex exec runs a command with bash -lc in the sandbox, as the cloudex user in its home directory, as an SSH login would. Its standard output and standard error come back as they’re printed, and cloudex exec exits with the command’s exit code.
One argument after -- is a shell command line, so &&, pipes and globs work in it. Several arguments are one command and its arguments, each kept whole, the way python3 -c 'print(42)' reads. Without --, every argument is the command and the current sandbox runs it.
| Flag | Default | Effect |
|---|---|---|
--root |
off | Run as root |
--cwd |
the home directory | Working directory; a relative one starts in the home directory |
--timeout |
10m |
Stop the command after this long, at most 1h |
-d, --detach |
off | Start the command in the background; see below |
A timeout, or Ctrl-C, stops the command and everything it started. exec has no terminal, and it doesn’t send standard input, so a command that reads it sees it end at once. Use cloudex ssh for interactive programs. Its output is text, and bytes that aren’t valid UTF-8 come back as U+FFFD. To put a file in a sandbox, or to get a binary file out, use cloudex cp. With --json, it waits and prints exitCode, stdout, stderr, timedOut and ms, with each stream cut at 1 MiB.
Background commands
cloudex exec -d -- npm run dev # start; prints its id
cloudex exec -d --timeout 2h -- make all # stop it after 2 hours
cloudex commands # list them
cloudex commands logs -f cm-1a2b3c4d # follow its output to the end
cloudex commands kill cm-1a2b3c4d # stop it and what it started
cloudex commands rm cm-1a2b3c4d # remove its record and output
cloudex exec -d starts a command and returns. The command keeps running in the sandbox with no time limit, unless --timeout sets one, and a dropped connection doesn’t stop it. Its standard output and standard error go to one log on the sandbox’s disk, which cloudex commands logs prints; with -f it keeps printing until the command ends and then exits with its exit code, or, for a command stopped by a signal, 128 plus the signal’s number, as bash does. Ctrl-C stops following, not the command.
cloudex commands shows each command’s state:
| State | Means |
|---|---|
running |
Still running |
exited N |
Ended by itself with exit code N |
killed (TERM) |
Stopped by a signal, from cloudex commands kill or anything else |
timed out |
Stopped by its --timeout |
lost |
The sandbox stopped while it ran |
A stop ends every running command, and a resume doesn’t start them again; put servers you want after every start in ~/.cloudex/start. The records and logs stay until cloudex commands rm removes them, and forks get a copy. Named saves leave them out.
A background command that has printed something in the last 10 minutes counts as activity for idle stop, like an agent; one that stays quiet longer lets the sandbox stop. Cloudflare’s 6-hour limit still applies to jobs that run longer, except on a node, which has none.
Copy files
cloudex cp report.csv :data/ # into the current sandbox's ~/data
cloudex cp ./site web:/srv/site # a directory
cloudex cp :app/dist ./dist # out of the current sandbox
cloudex cp web:/var/log/app.log - # to standard output
echo hello | cloudex cp - :hello.txt # from standard input
Name a path in a sandbox as SANDBOX:PATH, or :PATH for the current sandbox. Relative paths there start in the home directory. It works like cp -r: when the destination is a directory that exists, or ends with /, what you copy goes inside it; otherwise it’s created with that name. Files keep their permissions, and directories keep their symlinks. A local path that is a symlink to a directory copies that directory. A download makes the local directories it needs. -r, -R and -a are accepted and change nothing, since directories always copy whole.
A download can’t reach outside where you put it: it never writes through a symlink, leaves out symlinks that point outside it, and leaves out .git directories, whose hooks and settings could run commands on your computer. To bring a sandbox’s commits home, push them from the sandbox. A download also leaves out hard links, devices, and files the cloudex user can’t read, which --root reads. The summary that cloudex cp prints on standard error counts what it left out, except the files it couldn’t read.
Files are read and written as the cloudex user, so the sandbox’s permissions apply; --root reads and writes as root. A file is replaced whole, so nothing reads half of it. Cloudflare limits an upload to 100 MB at a time, compressed. For more, or to sync a folder repeatedly, use rsync through ssh-config.
CI jobs: cloudex run
cloudex run -- npm test
cloudex run --from node-base --out dist -- 'npm ci && npm run build'
cloudex run --env CI=1 --keep-on-failure -- make check
cloudex run does a whole job in one command. It:
- Starts a sandbox.
- Copies the current directory into it.
- Runs the command there, printing its output as it comes.
- Copies back what
--outnames. - Deletes the sandbox.
It exits with the command’s exit code, so a CI step fails when the command does. What --out copies back leaves out the same things as a download.
In a git repository it copies the files git would commit: tracked files, and new ones that .gitignore doesn’t exclude, but not .git itself. Elsewhere it copies everything under --dir. They go to ~/<the directory's name>, where the command runs.
--from starts from a named save, or a fork of a sandbox, instead of the plain image. Set up a sandbox once with your tools and dependencies, save it, and each run starts from that save with your latest files copied over it:
cloudex new --name node-base
cloudex exec node-base -- 'git clone https://github.com/you/app && cd app && npm ci'
cloudex save node-base node-base
cloudex run --from node-base --workdir app -- npm test # in ~/app, where node_modules is
The command runs as a background command, so it has no time limit unless you set --timeout, and a dropped connection doesn’t stop it; run reconnects for up to two minutes. Ctrl-C stops the command and deletes the sandbox; a second Ctrl-C quits at once and leaves the sandbox. A command stopped by its --timeout makes run exit with 124.
| Flag | Default | Effect |
|---|---|---|
--from |
the image | Start from this named save, or a fork of this sandbox |
--dir |
. |
The directory to copy |
--workdir |
~/<its name> |
Where the files go, and the command runs |
--no-upload |
off | Copy nothing |
--out |
none | A file or directory to copy back after, relative to the workdir; it lands at the same place under --dir. Repeatable. |
--env |
none | NAME=VALUE, repeatable. --env-file reads a file of them. |
--timeout |
none | Stop the command after this long |
--keep |
off | Keep the sandbox after |
--keep-on-failure |
off | Keep it when the command fails or is stopped, to look around with cloudex ssh |
--size, --name, --idle |
as cloudex new |
The sandbox’s size, name and idle stop |
--on |
Cloudflare | Run it on one of your nodes. An own-only token can use only nodes with Sysbox. |
In GitHub Actions, give the job your deployment’s URL and a token limited to its own sandboxes as secrets: cloudex tokens create github-actions --own --expires 90d makes one, and cloudex status prints the URL.
- run: curl -fsSL https://cloudex.build/install | CLOUDEX_INSTALL_DIR="$HOME/.local/bin" sh
- run: ~/.local/bin/cloudex run --from node-base -- npm test
env:
CLOUDEX_API_URL: ${{ secrets.CLOUDEX_API_URL }}
CLOUDEX_API_KEY: ${{ secrets.CLOUDEX_TOKEN }}