# 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](https://cloudex.build/docs/nodes.md), under the same deployment. Cloudex is open source under the MIT license, at [github.com/lucataco/cloudex](https://github.com/lucataco/cloudex).

These docs describe version 0.2.3. v0.2.3 makes nodes faster: ssh goes [straight to a node](https://cloudex.build/docs/nodes.md#direct-connections) on your LAN or tailnet, and sandboxes on nodes can be [forked](https://cloudex.build/docs/forks.md#on-a-node). v0.2.2 adds [nodes](https://cloudex.build/docs/nodes.md): sandboxes on a home server or VPS of your own. v0.2 adds a web [dashboard](https://cloudex.build/docs/dashboard.md), OpenCode, keys for six more AI providers, and [access tokens](https://cloudex.build/docs/tokens.md) 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](https://cloudex.build/docs/connect.md#preview-links).
- Optional: R2 turned on for the account, for [backups](https://cloudex.build/docs/sandboxes.md#backups). The free tier is enough.
- Optional: a Linux machine with Docker and root, to run sandboxes on as a [node](https://cloudex.build/docs/nodes.md).

## Quickstart

1. Install the CLI. On macOS and Linux:

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

   On Windows, in PowerShell:

   ```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.

   ```sh
   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](https://cloudex.build/docs/deploy.md).

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

   ```sh
   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.

   ```sh
   cloudex stop
   ```

   `cloudex resume` starts it again from the save. A sandbox also stops by itself after 30 minutes without activity; see [Idle stop](https://cloudex.build/docs/sandboxes.md#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 |

```sh
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](https://cloudex.build/docs/nodes.md) 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](https://cloudex.build/docs/deploy.md): tokens, preview domains, a second computer and updates
- [Nodes](https://cloudex.build/docs/nodes.md): sandboxes on a Linux machine of your own
- [Sandboxes](https://cloudex.build/docs/sandboxes.md): sizes, idle stop, saves and backups
- [Settings](https://cloudex.build/docs/settings.md): environment variables, files and a repo for each sandbox
- [Connect](https://cloudex.build/docs/connect.md): SSH, editors, `exec` and preview links
- [Provider keys](https://cloudex.build/docs/keys.md): Anthropic and OpenAI keys for agents that stay outside sandboxes
- [Limits](https://cloudex.build/docs/limits.md): what sandboxes can't do
