# Introduction 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 - [Install with your AI](/docs/install): paste `Set up box from https://box.simular.ai/install` into your coding agent and it adds box for you. - [MCP server](/docs/mcp): the server URL, sign-in, and how to add box to Claude, ChatGPT, Claude Code, Codex, Cursor, DeepSeek Harness or any MCP client. - Or, in a terminal: `npx @simular-ai/box connect` adds box to Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw and VS Code on your computer. - [Troubleshooting](/docs/troubleshooting): fixes for common setup problems, and how to reach us. ## 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. ## Guides - [Headless agents](/docs/headless): run `codex exec`, `claude -p` and other agents with no one at the keyboard. ## Support Email [support@simular.ai](mailto:support@simular.ai). --- # Install with your AI The steps a coding agent follows to add box to the app it runs in, and what a chat app tells you to do instead. Paste this into Claude Code, Codex, Cursor or Gemini CLI 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 to an agent that asks for it or fetches with a tool like `curl`, otherwise as the HTML page. Setting box up by hand, or in Claude, ChatGPT or Gemini? [MCP server](/docs/mcp) has every app's steps. > For agents: box is one remote MCP server at `https://mcp.box.simular.ai/mcp` (Streamable HTTP, OAuth sign-in). Read this page as text (`curl -fsSL https://box.simular.ai/install`, or your fetch tool), never by opening it in a browser or with computer use. A coding agent setting box up for someone follows [Steps for the agent](#steps-for-the-agent). If you are a chat app (Claude on claude.ai or the desktop app, ChatGPT, or the Gemini app) reading this for the person you're talking to, you can't add box yourself: give them only your own app's steps from [In a chat app](#in-a-chat-app), unless they ask about another app. Raw Markdown: https://box.simular.ai/install.md ## Steps for the agent 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. If the agent is running in the Codex app on Windows, it doesn't run the installer or edit `~/.codex/config.toml`: the Codex sandbox on Windows can't write to the Codex home folder. It gives the person the steps in [Codex app on Windows](#codex-app-on-windows) and goes on to step 4 once they have signed in. 2. **Add box to the app it is running in** with the installer, which also removes `box-control`, a second server older versions of this setup added: ```bash npx -y @simular-ai/box connect --client --yes ``` Put the app's id in place of ``: `claude-code` (also the Claude desktop app's Code tab), `codex`, `cursor`, `opencode`, `hermes`, `openclaw` or `vscode`. If it fails (no Node.js, or the app already has a different server named `box`), say so and add box by hand with the commands below. By hand: - 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://mcp.box.simular.ai/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://mcp.box.simular.ai/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://mcp.box.simular.ai/mcp" } } fs.mkdirSync(path.dirname(file), { recursive: true }) fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n") console.log("added box to " + file) ' ``` - Gemini CLI (adding again updates the entry): ```bash gemini mcp add --scope user --transport http box https://mcp.box.simular.ai/mcp ``` - DeepSeek Harness: run `dsh plugin add https://github.com/simular-ai/box-plugin/releases/download/dsh-v0.2.1/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, ChatGPT, and the Gemini app: an agent can't add a connector. Give the person only that app's steps from [In a chat app](#in-a-chat-app) (for Claude, the Add to Claude link first), unless they ask about another app, 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 app: they open Settings → MCP servers, select **Authenticate** next to box, sign in and click **Approve**. - Codex CLI: 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**. - Gemini CLI: they type `/mcp auth box`, sign in and click **Approve**. - OpenCode: the agent runs `opencode mcp auth box`. Hermes: `hermes mcp login box`. OpenClaw: `openclaw mcp login box`. VS Code signs in when the server starts. The person signs in in the browser and clicks **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 Also give them two or three of these prompts, word for word, to try in the new chat: - "Use box to open Chrome, search Google for "Simular", and summarize the top 3 results." - "Use box to open GitHub Trending and tell me what today's top 3 repositories do" - "Use box to go to news.ycombinator.com and give me today's top 5 stories in a table" 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. `npx @simular-ai/box doctor` checks the setup and prints a fix; [Troubleshooting](/docs/troubleshooting) lists the common problems. ## Codex app on Windows The Codex sandbox on Windows can't write to the Codex home folder, so the person adds box in the Codex app: 1. In the Codex app, open Settings, then select MCP servers. 2. Select Add server. Name it box, choose Streamable HTTP and paste the URL below. 3. Save, then select Restart. 4. Select Authenticate next to box, sign in to box and approve. In a chat, type /mcp to see it. The URL is `https://mcp.box.simular.ai/mcp`. The Codex app, the Codex CLI and the IDE extension share one config, so this covers all three. ## DeepSeek Harness (dsh) dsh can't sign in, so it uses a personal key. The agent installs the plugin; the person creates a key at [https://box.simular.ai/keys](https://box.simular.ai/keys) (**Create key** under Keys and devices; it is shown once) and sets it in their own terminal, never in the chat: ```bash dsh plugin add https://github.com/simular-ai/box-plugin/releases/download/dsh-v0.2.1/dsh-box.tgz export BOX_TOKEN=cb_your_key ``` The key goes in place of `cb_your_key`; adding the line to the shell profile keeps it. After a restart, box's tools show up in dsh as `mcp__box__*`. ## In a chat app Claude on the web or in the desktop chat, ChatGPT and the Gemini app add box as a connector, and only the person can do it. Give them only their own app's steps, unless they ask about another app. ### Claude Give the person the Add to Claude link first: one tap adds box, on a phone too. [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=box&connectorUrl=https%3A%2F%2Fmcp.box.simular.ai%2Fmcp) Claude opens with box filled in, on your phone or your computer. Tap Continue, then sign in to box and approve. If the link doesn't work, by hand: 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://mcp.box.simular.ai/mcp`. ### ChatGPT Adding happens once on chatgpt.com, in a browser on a computer (the ChatGPT app on iPhone and Android can't add one); after that box works in the ChatGPT app. Link the person to https://box.simular.ai/install?app=chatgpt, which opens these steps, and say that on a phone alone Claude adds box in one tap. 1. On a computer, open chatgpt.com/plugins (Plugins in ChatGPT’s sidebar). Click Add, then 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. Select I understand and want to continue, then Create as a plugin. Install the plugin, then 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://mcp.box.simular.ai/mcp`. No **Add custom MCP server**? Their ChatGPT plan or workspace may not allow custom servers yet. ### Gemini Adding happens once on gemini.google.com, on a computer; after that box works in the Gemini app too. Google allows custom apps only for a personal Google Account (not a work or school one), for people 18 or older in the US, in English, with Keep Activity on. Otherwise, [Gemini CLI](/docs/mcp#gemini-cli) works. 1. On a computer, open gemini.google.com. Click Settings, then Connected Apps (if you don’t see it, click Personal Intelligence first). 2. Under Custom apps, click Add a custom app and paste the URL below. Leave Advanced features empty. 3. Click Next, then sign in to box and approve. 4. In a chat, type @ and pick box, then ask for a task. Once added, box works in the Gemini mobile app too. The URL is `https://mcp.box.simular.ai/mcp`. ## Troubleshooting and support Start with `npx @simular-ai/box doctor`; [Troubleshooting](/docs/troubleshooting) lists the common problems. Support: [support@simular.ai](mailto:support@simular.ai). --- # MCP server The server URL, sign-in, and how to add box to each app, from ChatGPT, Claude and Gemini to Claude Code, Codex, Cursor or any MCP client. **Pick your app:** - [Claude](#claude-claudeai-and-the-desktop-app): One tap, on your phone or your computer. [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=box&connectorUrl=https%3A%2F%2Fmcp.box.simular.ai%2Fmcp) - [ChatGPT](#chatgpt): Adding happens once on chatgpt.com, on a computer; after that box works in the ChatGPT app. [Show the steps](#chatgpt) - [Claude Code, Codex, Cursor and more](#connect-with-one-command): One command in a terminal adds box to the coding apps on your computer. [Get the command](#connect-with-one-command) - [Gemini](#gemini-geminigooglecom): Add box once on gemini.google.com, on a computer; then it works in the Gemini app too. [Show the steps](#gemini-geminigooglecom) - [Another app](#any-other-mcp-client): Any MCP client, with the server URL; Gemini CLI, DeepSeek Harness and VS Code have their own steps below. [Show the steps](#any-other-mcp-client) > For agents: box is one remote MCP server at `https://mcp.box.simular.ai/mcp` (Streamable HTTP, OAuth sign-in). This page is the setup guide for every app. A coding agent setting box up for someone follows https://box.simular.ai/install instead, which runs the installer `npx @simular-ai/box connect`. If you are a chat app (Claude on claude.ai or the desktop app, ChatGPT, or the Gemini app), you can't add box yourself: give the person only your own app's steps, under [Claude](#claude-claudeai-and-the-desktop-app), [ChatGPT](#chatgpt) or [Gemini](#gemini-geminigooglecom), unless they ask about another app. If you are Claude, give them the Add to Claude link first (https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=box&connectorUrl=https%3A%2F%2Fmcp.box.simular.ai%2Fmcp). 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." - "Use box to open GitHub Trending and tell me what today's top 3 repositories do" - "Use box to go to news.ycombinator.com and give me today's top 5 stories in a table" ## Connect with one command Run this in a terminal (it needs Node.js 18.17 or later): ```bash npx @simular-ai/box connect ``` It finds the AI apps on this computer (Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw and VS Code), asks which ones should use box, and adds the box server to each in its own format. Other servers and settings in those files are left alone, each changed file gets a backup next to it, and running it again changes nothing. Each app then signs you in to box in the browser the first time it connects (OAuth); there is no key to paste. - `--client ` picks the apps, comma-separated: `claude-code`, `codex`, `cursor`, `opencode`, `hermes`, `openclaw`, `vscode`, `claude-desktop`. - `--yes` doesn't ask; with no `--client`, it uses every app it found. - `--dry-run` shows what would change without writing anything. - `--name ` uses another server name instead of `box`, when the app already has a different server called `box` (box.com's, for example). - `--auth key` (Hermes and OpenClaw only) uses a personal key instead of OAuth, for an always-on server with no browser. The key comes from `BOX_TOKEN` or a hidden prompt, never from the command line. - `npx @simular-ai/box doctor` checks box's setup in each app; `npx @simular-ai/box remove` undoes `connect`. Claude Desktop keeps remote servers as connectors you add in the app, so for it `connect` prints the steps. Claude on the web, ChatGPT, Gemini, Gemini CLI and DeepSeek Harness aren't covered: follow their steps under [Set up in your app](#set-up-in-your-app). The installer's source and README: [simular-ai/box-plugin](https://github.com/simular-ai/box-plugin/tree/main/cli). ## Server URL and sign-in box is one MCP server, named `box`: ```text https://mcp.box.simular.ai/mcp ``` **Added box before November 4, 2026?** Its URL used to be `https://relay.simular.cloud/mcp`. That URL still answers, but signing in through it can fail. Switch to the URL above: run the command below, which replaces the old entry, or in an app you set up by hand, remove box and add it again with the new URL. ```bash npx @simular-ai/box@latest connect ``` 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 `. 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 The installer above covers most coding apps. Claude adds box in one tap; the other apps take a few steps: ### Claude (claude.ai and the desktop app) [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=box&connectorUrl=https%3A%2F%2Fmcp.box.simular.ai%2Fmcp) Claude opens with box filled in, on your phone or your computer. Tap Continue, then sign in to box and approve. Claude Free allows one custom connector. On Team and Enterprise, an Owner adds box for the organization first. Or by hand: 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://mcp.box.simular.ai/mcp`. In the Claude desktop app, the live view shows in Chat and Code, not in Cowork. More in [The live view](/docs/troubleshooting#the-live-view). ### ChatGPT ChatGPT adds box as a custom MCP server, made into a plugin. ChatGPT can't add it for you; do these steps yourself. Adding happens once on chatgpt.com, on a computer (the ChatGPT app on iPhone and Android can't add one); after that box works in the ChatGPT app. 1. On a computer, open chatgpt.com/plugins (Plugins in ChatGPT’s sidebar). Click Add, then 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. Select I understand and want to continue, then Create as a plugin. Install the plugin, then 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://mcp.box.simular.ai/mcp`. Don't see **Add custom MCP server**? Your ChatGPT plan or workspace may not allow custom servers yet; [Claude](#claude-claudeai-and-the-desktop-app) can add box in one tap, on a phone too. Sign in to box once in ChatGPT's built-in browser for **Take control**, and refresh box's tools after an update. More in [The live view](/docs/troubleshooting#the-live-view). ### Gemini (gemini.google.com) Gemini adds box as a custom app. Gemini can't add it for you; do these steps yourself on the web (the mobile app can't add one, but uses it once it is added). Google allows custom apps only for a personal Google Account (not a work or school one), for people 18 or older in the US, in English, with Keep Activity on ([Google's help page](https://support.google.com/gemini/answer/17209137)). Otherwise use [Gemini CLI](#gemini-cli). 1. On a computer, open gemini.google.com. Click Settings, then Connected Apps (if you don’t see it, click Personal Intelligence first). 2. Under Custom apps, click Add a custom app and paste the URL below. Leave Advanced features empty. 3. Click Next, then sign in to box and approve. 4. In a chat, type @ and pick box, then ask for a task. Once added, box works in the Gemini mobile app too. The URL is `https://mcp.box.simular.ai/mcp`. ### Claude Code ```bash claude mcp add --transport http box https://mcp.box.simular.ai/mcp ``` Then run `/mcp` in Claude Code, pick **box** and choose **Authenticate**. Sign in and click **Approve** in the browser. After opening the live view, the model may also take a still screenshot; that's expected. More in [The live view](/docs/troubleshooting#the-live-view). ### Codex app 1. In the Codex app, open Settings, then select MCP servers. 2. Select Add server. Name it box, choose Streamable HTTP and paste the URL below. 3. Save, then select Restart. 4. Select Authenticate next to box, sign in to box and approve. In a chat, type /mcp to see it. The URL is `https://mcp.box.simular.ai/mcp`. The Codex app, the Codex CLI and the IDE extension share one config (`~/.codex/config.toml`), so adding box once covers all three. Mention box with `@box` so Codex doesn't pick a different app named Box. More in [The live view](/docs/troubleshooting#the-live-view). ### Codex CLI ```toml # ~/.codex/config.toml [mcp_servers.box] url = "https://mcp.box.simular.ai/mcp" # then sign in: codex mcp login box ``` `codex mcp login box` opens the browser to sign in. Mention box with `@box` so Codex doesn't pick a different app named Box. More in [The live view](/docs/troubleshooting#the-live-view). ### Cursor [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=box&config=eyJ1cmwiOiJodHRwczovL21jcC5ib3guc2ltdWxhci5haS9tY3AifQ%3D%3D) Cursor opens and asks to install box; click **Install**. Or add this to `~/.cursor/mcp.json`: ```json { "mcpServers": { "box": { "url": "https://mcp.box.simular.ai/mcp" } } } ``` Then open Cursor Settings → MCP and click **Login** next to box. ### VS Code [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=box&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.box.simular.ai%2Fmcp%22%7D) VS Code opens and shows box; click **Install**. Or run **MCP: Add Server** from the Command Palette, choose **HTTP**, paste `https://mcp.box.simular.ai/mcp` and name it `box`. VS Code asks you to sign in to box when the server starts. ### Gemini CLI ```bash gemini mcp add --scope user --transport http \ box https://mcp.box.simular.ai/mcp ``` Then start `gemini`, run `/mcp auth box`, sign in and click **Approve** in the browser. `/mcp` shows whether box is connected; `gemini mcp list` shows it from your shell. Gemini Code Assist's agent mode in VS Code reads the same `~/.gemini/settings.json`, so box shows up there too. ### 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.2.1/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 Keys and devices; 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://mcp.box.simular.ai/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 Paste this into Claude Code, Codex, Cursor or Gemini CLI and the agent adds box for you: ```text Set up box from https://box.simular.ai/install ``` [Install with your AI](/docs/install) has the steps it follows. ## Troubleshooting and support Start with `npx @simular-ai/box doctor`: it checks box's setup in each app and prints a fix for each problem it finds. [Troubleshooting](/docs/troubleshooting) lists the common problems, and support is at [support@simular.ai](mailto:support@simular.ai). --- # Headless agents Run codex exec, claude -p and other agents with no one at the keyboard. A headless agent runs with no one at the keyboard to sign in or approve a tool call. Sign in once interactively on the same machine first ([MCP server](/docs/mcp)); the app keeps that sign-in for headless runs. ## Codex (`codex exec`) Headless Codex never asks for approval, so it refuses every box tool that can change something (clicks, typing, the shell). Approve box's tools for one run: ```bash codex exec -c 'mcp_servers.box.default_tools_approval_mode="approve"' "Use box to take a screenshot" ``` To keep it, add `default_tools_approval_mode = "approve"` under `[mcp_servers.box]` in `~/.codex/config.toml`. Codex then runs every box tool without asking, also in interactive chats, and anything your AI reads on a web page can steer the box's browser and shell. Keep deleting or resetting a box behind a prompt: ```toml [mcp_servers.box] url = "https://mcp.box.simular.ai/mcp" default_tools_approval_mode = "approve" [mcp_servers.box.tools.box_delete] approval_mode = "prompt" ``` Don't use `--dangerously-bypass-approvals-and-sandbox` for this: it also turns off Codex's sandbox on your own computer. ## Claude Code (`claude -p`) Headless Claude Code can't ask for permission either, so allow box's tools for the run with `--allowedTools` and the server's prefix: `mcp__box` for a server you added in Claude Code as `box`, every tool of it, the shell included. Put the prompt right after `-p`: `--allowedTools` takes a list, and a prompt after it is read as one more tool name. ```bash claude -p "Use box to take a screenshot" --allowedTools mcp__box ``` If you added box only as a connector on claude.ai, its tools are named `mcp__claude_ai_box__…`, so allow `mcp__claude_ai_box` instead. If you added box both ways, Claude Code loads only the one you added in Claude Code and drops the claude.ai connector. A headless run can't open a browser to sign that one in, so sign it in interactively on the same machine first (`/mcp` in Claude Code). ## CI machines On a CI machine where nobody can sign in, use a personal key from [https://box.simular.ai/keys](https://box.simular.ai/keys) in a config file, kept in an environment variable rather than in the file. For Claude Code: ```json { "mcpServers": { "box": { "type": "http", "url": "https://mcp.box.simular.ai/mcp", "headers": { "Authorization": "Bearer ${BOX_TOKEN}" } } } } ``` ```bash claude -p "Use box to take a screenshot" --strict-mcp-config --mcp-config box-mcp.json --allowedTools mcp__box ``` `--strict-mcp-config` uses only the servers in that file. Keep the key in your CI's secret store, and revoke it at [https://box.simular.ai/keys](https://box.simular.ai/keys) when the job no longer needs it. --- # Troubleshooting Fixes for the common problems when adding box to an app, signing in or watching the live view, and how to reach support. Start with `npx @simular-ai/box doctor`: it checks box's setup in each app and that the endpoint answers, and prints a fix for each problem it finds. ## Common problems | Symptom | Fix | | --- | --- | | The browser page says "Can't connect this agent" | Sign in again; if it repeats, remove box and add it again. | | A headless run (`codex exec`, `claude -p`) has no box tools, or every box call is refused | See [Headless agents](/docs/headless). | | No box tools after signing in | Start a new chat. In Claude Code, `claude mcp list` shows whether `box` is connected; in Gemini CLI, `gemini mcp list`. | | 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 | Your credits are spent. Add credits or choose a plan on [Billing](https://box.simular.ai/billing). | The setup steps for each app are in [MCP server](/docs/mcp). ## The live view When your AI opens box's screen, it shows live in the chat. Each app has a quirk that can make it look broken: | App | What to know | | --- | --- | | Claude desktop app | The live view shows in Chat and Code. In Cowork, Claude takes screenshots and links the screen instead; switch to Chat or Code to watch live. | | Claude Code | The model may also take a still screenshot after opening the live view. That's expected. | | Codex (in the ChatGPT desktop app) | Mention box with `@box`, or pick it under **+** → **Apps**. A plain "use box" can be matched to a different file-storage app named Box. | | ChatGPT and the Codex app | **Take control** opens in the app's built-in browser. Sign in to box there once. | | Claude and ChatGPT phone apps | The live view shows in the chat, and **Full screen** opens it full-screen. **Take control** works as it does on a computer. | | ChatGPT, after a box update | ChatGPT may keep showing the old view. Open box in ChatGPT's settings, where your apps are listed, choose **Refresh**, then start a new chat. | **Keep visible** (picture-in-picture) only appears where the app supports it; no app offers it yet, on the web, desktop or phone. ## Support Email [support@simular.ai](mailto:support@simular.ai). Say which app you added box to and what went wrong.