DocsConnect

Use sandboxes

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

SSH

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

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.

scp, rsync and editors

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:

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:

# 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

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 covers both, and copying files with cloudex cp.

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:

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, 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.
  • 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.

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.

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.

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