# Connect to a sandbox

> Open a shell with cloudex ssh, reach sandboxes from scp, rsync and editors, run commands with cloudex exec, share ports as HTTPS preview links and revoke them, and forward ports.

Sandboxes have no public address. Every connection goes through your deployment's API: SSH and port forwarding over a WebSocket, commands through `exec`, and web servers through preview links.

That's the same for a sandbox on one of your [nodes](https://cloudex.build/docs/nodes.md): its agent keeps a connection to your deployment, and everything below reaches the sandbox through it, a little slower than on Cloudflare. A sandbox on a node that's offline can't be reached that way until it's back. The exception is SSH and what runs over it: from a computer on the node's LAN or tailnet, it goes [straight to the node](https://cloudex.build/docs/nodes.md#direct-connections).

## SSH

```sh
cloudex ssh                          # the current sandbox
cloudex ssh web                      # a sandbox by name or id
cloudex ssh web -- uname -a          # run one command
```

`cloudex ssh` runs your system's `ssh` with a proxy command that carries the connection over a WebSocket to your API, which connects it to port 22 in the sandbox. For a sandbox on a node, the proxy command also tries the node itself, and takes the [direct path](https://cloudex.build/docs/nodes.md#direct-connections) when it answers first. You log in as the `cloudex` user. Anything after `--` goes to `ssh`: options, or a command to run.

The CLI uses its own SSH key, `~/.config/cloudex/id_ed25519`, and adds it to the sandbox the first time you connect. The sandbox must be running; if it's stopped, `cloudex ssh` tells you to run `cloudex resume`.

## Port forwarding

Forward a port with ssh's `-L` option after `--`:

```sh
cloudex ssh web -- -L 3000:localhost:3000
```

While that session is open, `http://localhost:3000` on your computer reaches port 3000 in the sandbox. Only you can use it. To share a port with someone else, use a [preview link](#preview-links).

## scp, rsync and editors

```sh
cloudex ssh-config >> ~/.ssh/config
```

This adds a block to your SSH config so plain `ssh`, `scp`, `rsync` and editors reach a sandbox as `<id or name>.cloudex`:

```sh
ssh web.cloudex
scp notes.txt web.cloudex:
rsync -a ./app/ web.cloudex:app/
ssh -L 5173:localhost:5173 web.cloudex
```

Editors that open folders over SSH can use the same host name, such as `web.cloudex`. The block looks like this, with your own paths:

```text
# Cloudex sandboxes: ssh <id or name>.cloudex
Host *.cloudex
  User cloudex
  ProxyCommand '/usr/local/bin/cloudex' proxy %n 22
  IdentityFile /Users/you/.config/cloudex/id_ed25519
  IdentitiesOnly yes
  UserKnownHostsFile /Users/you/.config/cloudex/known_hosts
  StrictHostKeyChecking accept-new
  ServerAliveInterval 30
```

It names the path of the `cloudex` binary, so run `cloudex ssh-config` again if you move it. These connections don't resume a stopped sandbox; run `cloudex resume` first.

## Run a command: exec

```sh
cloudex exec -- npm test
cloudex exec web -- 'cd app && git status'
cloudex exec --root -- apt-get install -y ripgrep
```

`cloudex exec` runs a command with `bash -lc` as the `cloudex` user in its home directory, prints its output as it comes, and exits with the command's exit code. `exec -d` leaves a command running in the background. [Commands and files](https://cloudex.build/docs/commands.md) covers both, and copying files with `cloudex cp`.

## Preview links

```sh
cloudex host 3000
cloudex host web 8080
```

`cloudex host` prints an HTTPS link that serves a port in the sandbox on the preview domain you chose with `cloudex deploy --preview-domain`:

```text
https://3000-cx-7f3a2k-a1b2c3d4e5.example.com
```

- The link holds a secret token made from your deployment's API key, the sandbox and the port. Anyone who has the link can open it, and nobody can guess it. There is no other sign-in.
- The same sandbox and port give the same link until you [revoke it](#revoke-a-link), or the deployment's API key changes.
- Links work only while the sandbox is running. A request to a stopped sandbox gets an error that says to run `cloudex resume`; it doesn't start the sandbox.
- Requests to a link count as activity for [idle stop](https://cloudex.build/docs/sandboxes.md#idle-stop).
- Servers that listen only on `localhost` work, such as Vite, Django, Flask, Rails and uvicorn with their default settings. The first request starts a small relay in the sandbox, which takes a moment; it stops when the server does, and never holds the server's port. A first request with a body, such as a form POST, goes through too when the body is at most 1 MB. One with a bigger body gets a 503 that asks you to send it again.
- The server sees the link's host name in `Host` and `X-Forwarded-Host`, `X-Forwarded-Proto: https`, and the visitor's address in `X-Forwarded-For`. Visitors never appear to come from localhost, so tools that trust local requests, such as Rails' web console, don't open up to them. Vite's dev server accepts the preview domain without any configuration. Other dev servers that check the host name, such as webpack's or Angular's, need the preview domain in their allowed hosts.
- WebSockets work, so hot reload does too. When the dev server itself restarts, reload the page by hand: through a preview link, Vite's page doesn't notice the restart.
- Preview links need a preview domain. Without one, `cloudex host` says to run `cloudex deploy --preview-domain <your domain>`.
- Inside the sandbox, `cloudex host 3000` prints the same link; see [Inside the sandbox](https://cloudex.build/docs/sandboxes.md#inside-the-sandbox).

Fetching a preview link from a script with Python's `urllib` needs a `User-Agent` header: Cloudflare's Browser Integrity Check, on by default for your domain, answers urllib's default one with error 1010.

### Revoke a link

```sh
cloudex host web 3000 --revoke   # this port's link stops working
cloudex host web 3000            # a new link for the port
cloudex host web --list          # the links made since v0.1.14 that still work
cloudex host web --revoke-all    # every link to the sandbox, the desktop's too
```

A revoked link stops working at once, for everyone, and connections open through it, such as a desktop someone is watching, close. Asking for the port's link again gives a new one, which works until you revoke it in turn. `--list` shows the links made since Cloudex v0.1.14; `--revoke-all` also ends older ones.
