# 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

```sh
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](https://cloudex.build/docs/nodes.md) 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](https://cloudex.build/docs/connect.md#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](https://cloudex.build/docs/sandboxes.md#backups) and [named saves](https://cloudex.build/docs/saves.md) 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](https://cloudex.build/docs/sandboxes.md#saves).

[Nodes](https://cloudex.build/docs/nodes.md) 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](https://cloudex.build/docs/nodes.md#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:

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

   ```sh
   cloudex tokens approve BCDF-GHJK
   ```

The new computer gets an [access token](https://cloudex.build/docs/tokens.md) 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:

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

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