# Dashboard

> Your deployment's own web dashboard, with sandboxes, terminals, desktops, agents, commands, files, named saves, nodes and access, signed in from the CLI, with a code, or with a token.

```sh
cloudex dashboard
```

Your deployment serves a dashboard at its API URL, `https://cloudex-api.<your-subdomain>.workers.dev`. It needs no domain or setup of its own. `cloudex dashboard` opens it in your browser, already signed in. `cloudex dashboard my-box` opens it on that sandbox.

It has these pages:

- **Sandboxes:** each one's state, where it runs, size, idle stop and age, updated every 5 seconds. You can make new ones, from a fresh image or a [named save](https://cloudex.build/docs/saves.md), on Cloudflare or one of your [nodes](https://cloudex.build/docs/nodes.md), and stop, resume and delete them.
- **A sandbox,** with these tabs:
  - **Overview:** details, settings names, [preview links](https://cloudex.build/docs/connect.md#preview-links), forks and saves. For a sandbox on a node, the node it runs on, its isolation and its machine's CPUs and memory.
  - **Terminal:** shells in the sandbox.
  - **Desktop:** the sandbox's [desktop](https://cloudex.build/docs/desktop.md).
  - **Agents:** Claude Code, Codex and OpenCode conversations; start one, follow it, send messages and interrupt.
  - **Commands:** [background commands](https://cloudex.build/docs/commands.md#background-commands) and their output.
  - **Files:** browse, download a file or a directory as tar.gz, upload by dropping files, and delete.
- **Saves:** named saves, the node each was made on, and new sandboxes from one, on Cloudflare or a node.
- **Nodes,** for admins: your [nodes](https://cloudex.build/docs/nodes.md), with their state, isolation, host and sandboxes. **Add node** shows the command that installs a node's agent, once. Removing a node that has sandboxes says what happens to them first.
- **Access,** for admins: [tokens](https://cloudex.build/docs/tokens.md), dashboard sessions, sign-ins waiting for approval, and [provider keys](https://cloudex.build/docs/keys.md).

A `read` session sees the pages but can't change anything, and has no terminal or desktop. An own-only session sees only its own sandboxes.

## Sign in

| Way | How |
|---|---|
| From the CLI | `cloudex dashboard` makes a link that signs a browser in once, within 60 seconds, and opens it. `--no-open` prints the link instead, for a browser on another computer. A browser that's signed in already stays signed in as it was, and the link isn't used: sign out first to use it. |
| With a code | On the login page, **Get a code** shows a code such as `BCDF-GHJK`. Approve it with `cloudex tokens approve BCDF-GHJK` on a computer that's signed in, or in a dashboard that's signed in. |
| With a token | Paste a [token](https://cloudex.build/docs/tokens.md) or the admin key on the login page. The browser gets a session of its own; what you paste isn't kept. |

`cloudex login` on a computer without a key prints a link to approve its code in the dashboard, `<API URL>/login?code=BCDF-GHJK`. The page shows where the sign-in comes from and the role it asked for before you approve it. It starts at `user` (or `read`, if that was asked for); `admin` is given only if you choose it. **Access** lists the sign-ins waiting. Only approve a code you started yourself.

## Sessions

A browser's sign-in is a dashboard session. It's a kind of token, listed by `cloudex tokens` and on **Access** with a name such as `dashboard (Firefox on Linux)`.

- **Role:** it has the role of whatever signed it in. `cloudex dashboard` on a computer with a `read` token gives a `read` session.
- **How long it lasts:** 30 days from its last use. A session signed in with a code never lasts past the expiry chosen when it was approved.
- **Tokens:** a session signed in with a token acts for that token. It reaches the same own sandboxes, and it ends when the token is revoked or expires.
- **Signing out:** **Sign out** ends the session, as `cloudex tokens revoke <id>` does from anywhere. Open terminals and desktops close within a minute and go to the login page.
- **No sign-ins from a session:** a session can't make a sign-in link, and pasting one on the login page doesn't work. Use a token or the admin key.

## Terminal

Each terminal tab is a login shell in the sandbox. Tabs run as the `cloudex` user, with `sudo` and Docker. Choose **+ root** for a root shell.

- **Reconnecting:** each tab runs in a tmux session of its own. If the connection drops, the tab reconnects to the same shell, with what was running in it. Connections drop for a moment when the deployment is updated.
- **Closing a tab** ends its shell. Leaving the page doesn't, and the tabs come back when you return. Shell 1 in two browsers is the same shell, and both see it.
- **Selecting text:** hold Shift, or Option on a Mac, to select text with the mouse. The mouse wheel scrolls back.
- **Idle stop:** while the browser tab is visible, each open terminal tells the sandbox once a minute that someone is there, so it doesn't [stop for being idle](https://cloudex.build/docs/sandboxes.md#idle-stop). A terminal left in a hidden browser tab doesn't keep it up.
- **Stopped sandbox:** when a sandbox stops, its shells end. Resuming it starts new ones in the same tabs.

## Desktop

**Desktop** starts the sandbox's [desktop](https://cloudex.build/docs/desktop.md) the first time it opens. Installing it the first time takes a minute or two. The dashboard shows it with a viewer of its own, over its own connection to the desktop, so the desktop needs no preview link.

**Match this window's size** resizes the desktop to fit the browser window; otherwise the picture scales. **Clipboard** shows what's copied on the desktop, and sends text to the desktop's clipboard for pasting there.

## Security

- **Session cookie:** the session lives in a cookie that page scripts can't read. It's sent only to your deployment's host, and never with a request another site starts.
- **Cookie requests:** every API request that uses the cookie must also come from the dashboard's own pages, with its Origin and a header that another site can't add. A token or the admin key as the bearer works as before.
- **Sandbox content:** nothing from a sandbox is ever served as a page of the dashboard's host:
  - agent output, command output and file names show as text;
  - downloads are attachments that can't run as pages;
  - the desktop uses the dashboard's own viewer;
  - preview links open on your preview domain, in a new tab.
- **Links in the terminal** open in a new tab, `http` and `https` ones only.
- **After signing in,** the login page goes only to the dashboard's own pages.
- **Content Security Policy:** the dashboard's pages allow no inline scripts and no scripts from elsewhere, and can't be framed.

## Browsers

These versions or newer:

- Chrome or Edge 111;
- Firefox 115;
- Safari 16.4.

Uploads in the dashboard go up to 100 MB a file; [`cloudex cp`](https://cloudex.build/docs/commands.md#copy-files) has no limit.
