DocsOverview

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, prompt and attach use 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

  1. Install the CLI. On macOS and Linux:

    curl -fsSL https://cloudex.build/install | sh
    

    On Windows, in PowerShell:

    irm https://cloudex.build/install.ps1 | iex
    
  2. 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.com
    

    Use a domain you have in the same account, or leave out --preview-domain if you don’t want preview links. The first deploy takes a few minutes. See Deploy and update.

  3. Create a sandbox and open a shell in it:

    cloudex new --name web
    cloudex ssh
    

    The new sandbox becomes the current one, so later commands act on it when you don’t name a sandbox.

  4. Stop it when you’re done. Its disk is saved and its container stops.

    cloudex stop
    

    cloudex resume starts 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 the docker group, 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, exec and preview links
  • Provider keys: Anthropic and OpenAI keys for agents that stay outside sandboxes
  • Limits: what sandboxes can’t do

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