Get started
Deploy and update
Install Cloudex in your Cloudflare account with cloudex deploy, use it from a second computer, check the setup, and update the CLI and the deployment.
Deploy
cloudex deploy --preview-domain example.com
cloudex deploy reads a Cloudflare API token from $CLOUDFLARE_API_TOKEN, or asks you to paste one. It prints a link that opens the Cloudflare dashboard with the token’s permissions filled in; cloudex deploy --help prints the same link. The token needs these account permissions:
| Permission | Used for |
|---|---|
| Workers Scripts: Edit | The API Worker |
| Workers Containers: Edit | The sandbox image and containers |
| D1: Edit | The list of sandboxes |
| Account Settings: Read | Finding the account |
| Workers Routes: Edit | Preview links |
| DNS: Edit | Preview links |
| Zone: Read | Preview links |
| Workers R2 Storage: Edit | Backups |
If the token lacks a permission that a step needs, deploy stops and names the permission to add.
Then it works through these steps:
- Checks the token, and that the account can run containers, which needs Workers Paid. If the token reaches more than one account, pick one with
--account-idor$CLOUDFLARE_ACCOUNT_ID. - Copies the sandbox image of the CLI’s version, such as
ghcr.io/lucataco/cloudex-base:v0.2.3, into your account’s container registry, and waits until Cloudflare has it ready to run. You don’t need Docker or Node.js on your computer.--imageinstalls a different image. Nodes pull the same image, by its digest, fromghcr.io. - Finds or creates the D1 database
cloudexand the R2 bucketcloudex-backups. - Uploads the API Worker,
cloudex-api, with the admin key as a Worker secret, and gives it its container application and its workers.dev URL. With a preview domain, it routes*.<domain>/*to the Worker. The first deploy makes the key; later deploys from the same computer keep it. - With a preview domain, adds a proxied
*.<domain>DNS record. - Waits for the API, then starts a test sandbox and deletes it, because a newly pushed image can take a while to reach every Cloudflare host.
--skip-checkskips this.
As soon as the Worker is uploaded, deploy saves the API URL and the admin key on this computer, so a deploy that is interrupted or fails its test sandbox doesn’t lose the key. At the end it prints the API URL, https://cloudex-api.<your-subdomain>.workers.dev. If you later change the account’s workers.dev subdomain, run cloudex deploy again: it finds the API at its new address, keeps the key, and saves the new URL. Other computers then need cloudex login --url with the new one.
Preview domain
--preview-domain example.com serves preview links on that domain. It must be a zone in the same Cloudflare account. Cloudex adds a proxied *.example.com DNS record and routes *.example.com/* to its Worker. Requests for your other subdomains, such as www.example.com, pass through to their origins unchanged.
Preview links look like https://3000-cx-7f3a2k-<token>.example.com. Everything sits in one label under the domain, so the zone’s Universal SSL certificate covers it.
Running cloudex deploy again keeps the preview domain. --preview-domain '' turns preview links off. When you turn them off, or move them to another domain, deploy removes the old domain’s route and the *.<domain> record it added.
Backups and R2
cloudex deploy creates the R2 bucket for backups and named saves when R2 is turned on for the account. The free tier is enough for backups. If R2 is off, or the token can’t use it, deploy says so and carries on with backups and named saves off. Turn on R2 Object Storage in the Cloudflare dashboard, then run cloudex deploy again.
cloudex status shows whether backups are on.
Run it again to update
Running cloudex deploy again updates the API and the sandbox image. It keeps your sandboxes, your API key and your preview domain.
Sandboxes keep running during an update. Open connections, such as cloudex ssh sessions and desktops, move to the new version within about 5 minutes and may drop when they do; reconnect if one does. A sandbox that resumes from a save keeps the image it was saved on; see Saves.
Nodes reconnect by themselves, and their sandboxes keep running. Their agents don’t update themselves: after an update, run the installer again on each node with the new version, as Updating the agent says. cloudex doctor warns about a node whose agent’s version differs from the deployment’s.
A second computer
Don’t run cloudex deploy on a second computer. It would give the deployment a new API key, and the first computer would stop working. Instead:
-
On the new computer, log in with the URL:
cloudex login --url https://cloudex-api.<your-subdomain>.workers.devIt shows a code, such as
BCDF-GHJK, and waits. -
On the computer that already works, approve it:
cloudex tokens approve BCDF-GHJK
The new computer gets an access token of its own, which you can revoke without touching the first one. The URL works without https:// too. To use a key instead, cloudex login --key asks for one, and a key in $CLOUDEX_API_KEY or on standard input is used as it is.
If cloudex deploy finds a running deployment whose key this computer doesn’t have, it asks before replacing the key. cloudex deploy --yes replaces it without asking.
Check the setup
cloudex status checks the connection to your deployment:
API https://cloudex-api.example.workers.dev (version v0.2.3)
Auth the admin key
Key hidden (--show-key prints it; for another computer, cloudex login there and approve its code with cloudex tokens approve)
Previews example.com
Backups on: /home goes to the R2 bucket cloudex-backups on each stop
Current cx-7f3a2k
cloudex status also checks the key. If the API rejects it, status says how to log in again and exits with status 1. If the deployment runs an older version than the CLI, an Update line says to run cloudex deploy.
cloudex doctor looks for problems. It checks that ssh is installed, that a deployment is configured, that its API answers, that it isn’t older than the CLI and that the key works. When $CLOUDFLARE_API_TOKEN is set, it also checks that the account can run containers. Each line starts with ok or fix, and it exits with status 1 if anything needs fixing. Lines that start with warn are about nodes: one that never joined, is offline, runs another version’s agent, fails its isolation self-test, is low on disk, or whose clock is off.
Update
cloudex update
cloudex update downloads the latest release of the CLI, checks it against the release’s checksums and replaces the running binary. If your deployment runs an older version, it then offers to run cloudex deploy, which keeps your sandboxes. Sandboxes that are running keep the old version until they stop. cloudex update --check only says what’s out of date. cloudex --version prints the CLI’s version.
A CLI or SDK newer than the deployment can ask for something the deployment doesn’t have. The error then says the deployment is older and to update it with cloudex deploy.
Once a day, the CLI checks for a new release and mentions it after a command. Set CLOUDEX_NO_UPDATE_CHECK=1 to turn that off.
Files on your computer
The CLI keeps its settings in ~/.config/cloudex, or in $CLOUDEX_CONFIG_DIR when that’s set:
| File | What it holds |
|---|---|
config.json |
The API URL, the admin key, the preview domain and the current sandbox. Only your user can read it. |
id_ed25519 |
The SSH key the CLI uses for sandboxes. It’s added to a sandbox the first time you connect. |
known_hosts |
The SSH host keys of your sandboxes |
$CLOUDEX_API_URL and $CLOUDEX_API_KEY override the saved deployment, and --api-url overrides the URL for one command. The CLI and the SDKs send the saved key only to the saved URL. With any other URL, set $CLOUDEX_API_KEY as well.