Get started
Get started
What Cloudex is, what you need, and how to go from installing the CLI to a shell in your first sandbox.
Cloudex gives coding agents Linux computers that run in your own Cloudflare account. Each one is called a sandbox: an Ubuntu machine with a shell, SSH, Docker, Node, Python, Claude Code, Codex and OpenCode. Stopping a sandbox saves its disk. Resuming it brings back your files, installed packages and agent logins.
There is no Cloudex service in between. cloudex deploy installs the API in your Cloudflare account, your code and keys stay there, and Cloudflare bills you directly. Sandboxes can also run on a Linux machine of your own, called a node, under the same deployment. Cloudex is open source under the MIT license, at github.com/lucataco/cloudex.
These docs describe version 0.2.3. v0.2.3 makes nodes faster: ssh goes straight to a node on your LAN or tailnet, and sandboxes on nodes can be forked. v0.2.2 adds nodes: sandboxes on a home server or VPS of your own. v0.2 adds a web dashboard, OpenCode, keys for six more AI providers, and access tokens with sign-in by code. v0.1 commands, API routes and SDK calls work unchanged.
What you need
- A Cloudflare account on Workers Paid ($5 a month). Containers need it. The account also needs a workers.dev subdomain; if it has none, open Workers & Pages in the Cloudflare dashboard once to choose one.
- An OpenSSH client.
cloudex ssh,promptandattachuse it. - Optional: a domain in the same Cloudflare account, for preview links.
- Optional: R2 turned on for the account, for backups. The free tier is enough.
- Optional: a Linux machine with Docker and root, to run sandboxes on as a node.
Quickstart
-
Install the CLI. On macOS and Linux:
curl -fsSL https://cloudex.build/install | shOn Windows, in PowerShell:
irm https://cloudex.build/install.ps1 | iex -
Deploy Cloudex to your Cloudflare account. It asks for a Cloudflare API token and prints a link that creates one with the right permissions.
cloudex deploy --preview-domain example.comUse a domain you have in the same account, or leave out
--preview-domainif you don’t want preview links. The first deploy takes a few minutes. See Deploy and update. -
Create a sandbox and open a shell in it:
cloudex new --name web cloudex sshThe new sandbox becomes the current one, so later commands act on it when you don’t name a sandbox.
-
Stop it when you’re done. Its disk is saved and its container stops.
cloudex stopcloudex resumestarts it again from the save. A sandbox also stops by itself after 30 minutes without activity; see Idle stop.
Install options
The macOS and Linux installer puts cloudex in /usr/local/bin when it can write there, and in ~/.local/bin otherwise. It supports x86-64 and ARM64. Two environment variables change what it does:
| Variable | Effect |
|---|---|
CLOUDEX_VERSION |
Install a given release, such as v0.1.17, instead of the latest |
CLOUDEX_INSTALL_DIR |
Install into this directory |
curl -fsSL https://cloudex.build/install | CLOUDEX_VERSION=v0.1.17 sh
The Windows installer also reads CLOUDEX_VERSION. To update an installed CLI, run cloudex update.
What goes into your account
cloudex deploy sets up these pieces in your Cloudflare account:
| Piece | What it does |
|---|---|
Worker cloudex-api |
The API at https://cloudex-api.<your-subdomain>.workers.dev, SSH and port connections, and preview links |
| A Durable Object per sandbox | Starts, stops, saves and times out its container, and connects you to it |
| A container per sandbox | The Ubuntu machine itself, from the cloudex-base image copied into your account’s registry. A sandbox on a node runs on the node instead. |
| A Durable Object per node | Keeps the connection to a node’s agent, when you add nodes |
D1 database cloudex |
The list of sandboxes |
R2 bucket cloudex-backups |
Backups of each sandbox’s /home, when R2 is on |
A proxied *.<domain> DNS record and route |
Preview links, when you give a preview domain |
What’s in a sandbox
The default image is Ubuntu 24.04 for x86-64 with:
- Node.js 22, Python 3 with pip and venv, and build-essential
- git, tmux, rsync, curl, wget, jq, zip, vim-tiny, htop and common network tools
- Docker Engine with the buildx and compose plugins
- Claude Code 2.1.318, Codex 0.166.0, OpenCode 2.2.5 and the GitHub CLI (
gh). The agents stay at the versions this release was tested with, and Claude Code’s and OpenCode’s updaters are off. - A user named
cloudex(uid 1000) with passwordless sudo, in thedockergroup, with its home in/home/cloudex
You can install anything else with apt, npm or pip. A save keeps it.
Next
- Deploy and update: tokens, preview domains, a second computer and updates
- Nodes: sandboxes on a Linux machine of your own
- Sandboxes: sizes, idle stop, saves and backups
- Settings: environment variables, files and a repo for each sandbox
- Connect: SSH, editors,
execand preview links - Provider keys: Anthropic and OpenAI keys for agents that stay outside sandboxes
- Limits: what sandboxes can’t do