# 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 <app> --yes
   ```

   Put the app's id in place of `<app>`: `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).