Use sandboxes
Tokens and sign-in
Give CI, coding agents and your other computers API keys of their own, with a role, limited to their own sandboxes if you like, expiring, and revocable at once. Sign a computer in with a code.
cloudex deploy makes one admin key, which can do everything. Access tokens are API keys of their own for everything else that uses your deployment: a CI job, a coding agent, a second computer, a teammate. Each has a role, can be limited to the sandboxes it makes, can expire, and stops working the moment you revoke it.
cloudex tokens create ci --own --expires 90d # prints the secret once
cloudex tokens # lists them, with when each was last used
cloudex tokens revoke tk-a2b3c4d5 # it stops working at once
A token works wherever the admin key does: as CLOUDEX_API_KEY for the CLI and SDKs, or as the bearer token for the API.
Roles
| Role | Can |
|---|---|
admin |
Everything, including tokens, provider keys and adding and removing nodes |
user (default) |
Everything to sandboxes and named saves: make, connect, exec, agents, files, preview links, settings, forks. List nodes and make sandboxes on them. Not tokens, provider keys, or adding and removing nodes. |
read |
List sandboxes, saves and nodes, show them, read agent events, command output and files. No exec, SSH, preview links or changes. |
--own limits a user or read token to the sandboxes it makes, and forks of them. It doesn’t see other sandboxes at all: cloudex ls leaves them out, and naming one gets “no sandbox named …”. It can start from any named save, as cloudex run --from does, but not make, replace or delete one, since other sandboxes start from saves. Sandboxes made with the admin key, or another token, belong to no own-only token.
An own-only token can’t make sandboxes on a node whose isolation is plain Docker, or none: CI runs code from pull requests, and code that escapes its container there is root on the node. It can use nodes with Sysbox. It sees every node in the list.
--expires takes a time such as 12h, 30d or never (the default). An expired token stops working, and cloudex tokens stops listing it.
Only the admin key or an admin token can make, list and revoke tokens.
Sign in another computer
On a computer without a key, cloudex login asks your deployment for a token and shows a code:
$ cloudex login --url https://cloudex-api.example.workers.dev
To sign this computer in, run this on a computer that already uses https://cloudex-api.example.workers.dev:
cloudex tokens approve BCDF-GHJK
Waiting for it (the code works for 10 minutes; Ctrl-C to stop)...
On a computer that already uses the deployment, approve it:
cloudex tokens approve # lists the sign-ins waiting
cloudex tokens approve BCDF-GHJK # shows where it comes from, and asks
cloudex tokens approve BCDF-GHJK --own --expires 7d
cloudex tokens deny BCDF-GHJK
The new computer gets a token of its own, named after it (--name on cloudex login changes that), which expires in 90 days unless --expires says otherwise. Its role is user, or read if it asked for read with --role; it gets admin only when --role admin on approve says so, whatever it asked for, and approve says what it asked for. Only approve a code you started yourself: whoever has the other computer gets the token.
cloudex login also prints a link, <API URL>/login?code=BCDF-GHJK, that approves the code in the dashboard, which shows the same details first.
cloudex login --key asks for a key instead, and a key in $CLOUDEX_API_KEY or on standard input is used as it is, as before.
Dashboard sessions
A browser signed in to the dashboard has a session, a token of the kind session, which cloudex tokens lists with a name such as dashboard (Safari on macOS):
- Role: it has the role of whatever signed it in.
- How long it lasts: 30 days from its last use. One signed in with a code never lasts past the expiry chosen when it was approved.
- Revoking it signs that browser out at once. Its open terminals and desktops close within a minute.
- It can’t sign in anything else: a session can’t make a dashboard link or another session.
- A session signed in with a token acts for that token, reaching the same own sandboxes, and goes when the token is revoked.
Coding agents and CI
An agent on your computer that needs its own access can sign in the same way. With --json, cloudex login prints the code as its first line, so the agent can show it to you while it waits:
cloudex login --url https://cloudex-api.example.workers.dev --json
# {"approveWith":"cloudex tokens approve BCDF-GHJK","expiresIn":600,"userCode":"BCDF-GHJK"}
For CI, make an own-only token and give the job your deployment’s URL and the token as secrets:
cloudex tokens create github-actions --own --expires 90d
- run: curl -fsSL https://cloudex.build/install | CLOUDEX_INSTALL_DIR="$HOME/.local/bin" sh
- run: ~/.local/bin/cloudex run --from node-base -- npm test
env:
CLOUDEX_API_URL: ${{ secrets.CLOUDEX_API_URL }}
CLOUDEX_API_KEY: ${{ secrets.CLOUDEX_TOKEN }}
The job can then start, use and delete its own sandboxes, and nothing else.
How it works
- A token’s secret looks like
cx_a2b3c4d5_…. Your deployment keeps only its SHA-256, in its D1 database, so a copy of the database lets nobody in. The secret is shown once, when the token is made. - Every request reads the token’s row, so a revoked token fails on its next request. An open terminal, desktop or
cloudex sshconnection checks about once a minute, and closes once its token is revoked or expires.cloudex tokensshows when each was last used, to the minute. - Tokens don’t depend on the admin key: they keep working after
cloudex deploy --yesreplaces it. - Device sign-in follows RFC 8628. Codes last 10 minutes, and up to 20 can wait at once, 3 from any one address. The approver sees the computer’s name, address and country.
cloudex statussays which token this computer uses. The API and SDKs make and revoke tokens too.