# box docs

box is a cloud Linux desktop for your AI, added to the app you already use as one remote MCP server.

box gives your AI a computer of its own: a cloud Ubuntu desktop with Chrome and a shell, which your AI drives over MCP while your own computer stays free. You can watch it live at [https://box.simular.ai/box](https://box.simular.ai/box) and take control when you need to.

## Start here

- [Connect box over MCP](/docs/mcp): add box to Claude, ChatGPT, Claude Code, Codex, Cursor, DeepSeek Harness or any MCP client, and sign in.

## For agents and LLMs

Every page is also plain Markdown: add `.md` to its URL, as in [/docs/mcp.md](/docs/mcp.md). [/docs/llms.txt](/docs/llms.txt) lists the pages, and [/llms-full.txt](/llms-full.txt) has all of them in one file.

## Support

Email [support@simular.ai](mailto:support@simular.ai).

---

# Connect box over MCP

Add box to Claude, ChatGPT, Claude Code, Codex, Cursor or any MCP client, so your AI can use a cloud computer of its own.

> For agents: box is one remote MCP server at `https://relay.simular.cloud/mcp` (Streamable HTTP, OAuth sign-in). This page is the setup guide; to set box up for someone, follow [Set up with a coding agent](#set-up-with-a-coding-agent). ChatGPT and Claude on the web can't add box themselves: give the person the steps under [ChatGPT](#chatgpt) or [Claude](#claude-claudeai-and-the-desktop-app). Raw Markdown: https://box.simular.ai/docs/mcp.md

box is a cloud Linux desktop for your AI. Add it to your AI app as a remote MCP server and the AI gets a real computer of its own: Chrome, a shell and a full Ubuntu desktop. It can browse, click, type, read the screen and run commands there, while your own computer stays free.

- **A desktop, ready on first connect.** One box per account, with Chrome and a persistent shell.
- **Sleeps when idle.** It wakes in about a second when your AI connects; files and state persist.
- **Watch it live.** See the screen at [https://box.simular.ai/box](https://box.simular.ai/box) and take control when you need to.

Once box is connected, try asking your AI:

- "Use box to open Chrome, search Google for "Simular", and summarize the top 3 results."
- "Open GitHub Trending and tell me what today's top 3 repositories do"
- "Go to news.ycombinator.com and give me today's top 5 stories in a table"

## Server URL and sign-in

box is one MCP server, named `box`:

```text
https://relay.simular.cloud/mcp
```

You sign in with your Simular account the first time your AI connects (MCP authorization, OAuth 2.0): your app opens a browser page where you approve which boxes it may use and for how long. There is no key to copy or paste.

For an app that can't sign in and can only send a fixed header, create a personal key at [https://box.simular.ai/keys](https://box.simular.ai/keys) and set it in the app's config as `Authorization: Bearer <key>`. The key is shown once; keep it out of chats and shared files.

Every app you connected and every key is listed at [https://box.simular.ai/keys](https://box.simular.ai/keys), where you can revoke any of them.

## Set up in your app

### Claude (claude.ai and the desktop app)

1. In Claude (claude.ai or the desktop app), open Settings → Connectors.
2. Click Add custom connector. Name it box and paste the URL below; leave the advanced settings empty.
3. Click Connect, sign in to box and approve. Then turn box on in a chat’s tools menu.

The URL is `https://relay.simular.cloud/mcp`.

### ChatGPT

ChatGPT adds box as a custom MCP server plugin. ChatGPT can't add it for you; do these steps yourself. Your workspace admin may need to allow custom MCP servers.

1. In ChatGPT, open Plugins (chatgpt.com/plugins), click Add and choose Add custom MCP server.
2. Name it box. Under Connection, paste the URL below as the Server URL, and choose OAuth as the authentication.
3. Confirm the warning (I understand and want to continue), click Create as a plugin, then install it. Sign in to box and approve when asked.
4. In a chat, type @ and pick box, then ask for a task.

The URL is `https://relay.simular.cloud/mcp`.

### Claude Code

```bash
claude mcp add --transport http box https://relay.simular.cloud/mcp
```

Then run `/mcp` in Claude Code, pick **box** and choose **Authenticate**. Sign in and click **Approve** in the browser.

### Codex

```toml
# ~/.codex/config.toml
[mcp_servers.box]
url = "https://relay.simular.cloud/mcp"

# then sign in: codex mcp login box
```

`codex mcp login box` opens the browser to sign in.

### Cursor

Add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "box": {
      "url": "https://relay.simular.cloud/mcp"
    }
  }
}
```

Then open Cursor Settings → MCP and click **Login** next to box.

### DeepSeek Harness (dsh)

dsh can't sign in, so it uses a personal key. Install the plugin, then set the key in your own terminal:

```bash
dsh plugin add https://github.com/simular-ai/box-plugin/releases/download/dsh-v0.1.0/dsh-box.tgz
export BOX_TOKEN=cb_your_key
```

Create the key at [https://box.simular.ai/keys](https://box.simular.ai/keys) (**Create key** under Personal keys; it is shown once), put it in place of `cb_your_key`, add the line to your shell profile to keep it, and restart dsh. box's tools show up as `mcp__box__*`.

### Any other MCP client

Add one remote MCP server, `box`, Streamable HTTP, at `https://relay.simular.cloud/mcp`, with no header. Your app signs you in the first time it connects. If it can't sign in, use a personal key as above.

## Set up with a coding agent

You can also paste this into Claude Code, Codex or Cursor and let the agent do it:

```text
Set up box from https://box.simular.ai/install
```

`https://box.simular.ai/install` serves this page as Markdown. An agent setting box up for someone does the following.

1. **Check first.** If box's `shell` and `box_list` tools are already available in the session, box is set up; skip to step 4.
2. **Add box to the app it is running in**, removing `box-control`, a second server older versions of this setup added.
   - Claude Code (also the Claude desktop app's Code tab):

     ```bash
     claude mcp remove --scope user box-control >/dev/null 2>&1; claude mcp remove --scope user box >/dev/null 2>&1
     claude mcp add --scope user --transport http box https://relay.simular.cloud/mcp
     ```

   - Codex: write `[mcp_servers.box]` to `~/.codex/config.toml` and leave the rest of the file alone:

     ```bash
     node -e '
     const fs = require("fs"), path = require("path"), os = require("os")
     const file = path.join(os.homedir(), ".codex", "config.toml")
     let text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : ""
     text = text.replace(/^\[mcp_servers\.box(-control)?\][^\[]*/gm, "")
     fs.mkdirSync(path.dirname(file), { recursive: true })
     fs.writeFileSync(file, text.replace(/\n*$/, "\n") + "\n[mcp_servers.box]\nurl = \"https://relay.simular.cloud/mcp\"\n")
     console.log("added box to " + file)
     '
     ```

   - Cursor: merge into `~/.cursor/mcp.json` and keep the servers already there:

     ```bash
     node -e '
     const fs = require("fs"), path = require("path"), os = require("os")
     const file = path.join(os.homedir(), ".cursor", "mcp.json")
     const config = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {}
     const { "box-control": _old, ...servers } = config.mcpServers || {}
     config.mcpServers = { ...servers, box: { url: "https://relay.simular.cloud/mcp" } }
     fs.mkdirSync(path.dirname(file), { recursive: true })
     fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n")
     console.log("added box to " + file)
     '
     ```

   - DeepSeek Harness: run `dsh plugin add https://github.com/simular-ai/box-plugin/releases/download/dsh-v0.1.0/dsh-box.tgz`, then tell the person to create a key at https://box.simular.ai/keys and set it themselves, as in [DeepSeek Harness](#deepseek-harness-dsh). Restarting dsh ends the session, so show the summary in step 4 before they restart.
   - Claude on the web or in the desktop chat, and ChatGPT: an agent can't add a connector. Give the person the steps in [Claude](#claude-claudeai-and-the-desktop-app) or [ChatGPT](#chatgpt) and stop.
3. **Have the person sign in.** Only the person can approve, in their browser:
   - Claude Code: they type `/mcp`, pick **box**, choose **Authenticate**, sign in and click **Approve**.
   - Codex: the agent runs `codex mcp login box`; the person signs in in the browser that opens and clicks **Approve**.
   - Cursor: they open Cursor Settings → MCP, click **Login** next to box, sign in and click **Approve**.

   The approval page is https://box.simular.ai/oauth/authorize. It asks which boxes the app may use and for how long; the defaults are fine.
4. **Tell the person box is ready**, with these links, and to start a new chat (or restart the app) so the box tools load:
   - Watch: https://box.simular.ai/box
   - Keys: https://box.simular.ai/keys (see or revoke access)
   - Support: support@simular.ai

Rules for the agent: run the commands itself and explain them in plain words; never ask for a key, and never repeat one in the chat; if a step fails, say what went wrong and stop rather than retrying in a loop.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| The browser page says "Can't connect this agent" | Sign in again; if it repeats, remove box and add it again. |
| No box tools after signing in | Start a new chat. In Claude Code, `claude mcp list` shows whether `box` is connected. |
| Signed out later | Access lasts the days chosen on the approval page; sign in again the same way. Connected apps and keys are listed on [Keys](https://box.simular.ai/keys). |
| The model says credits are used up | The free daily credit is spent. It refreshes daily, or add credit on [Billing](https://box.simular.ai/billing). |

## Support

Email [support@simular.ai](mailto:support@simular.ai).