DocsDeploy and update

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:

  1. 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-id or $CLOUDFLARE_ACCOUNT_ID.
  2. 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. --image installs a different image. Nodes pull the same image, by its digest, from ghcr.io.
  3. Finds or creates the D1 database cloudex and the R2 bucket cloudex-backups.
  4. 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.
  5. With a preview domain, adds a proxied *.<domain> DNS record.
  6. 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-check skips 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:

  1. On the new computer, log in with the URL:

    cloudex login --url https://cloudex-api.<your-subdomain>.workers.dev
    

    It shows a code, such as BCDF-GHJK, and waits.

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

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