Connect modebox to your agent.

01 install

Install the CLI

It's also the MCP server. Needs Rust 1.96 or later.

Or download it from the latest release:

curl -LO https://github.com/farming-labs/modebox/releases/latest/download/modebox-aarch64-apple-darwin.tar.gz
curl -LO https://github.com/farming-labs/modebox/releases/latest/download/modebox-aarch64-apple-darwin.tar.gz.sha256
shasum -a 256 -c modebox-aarch64-apple-darwin.tar.gz.sha256
tar xzf modebox-aarch64-apple-darwin.tar.gz
sudo mkdir -p /usr/local/bin
sudo mv modebox-aarch64-apple-darwin/modebox /usr/local/bin/
modebox --version

On another machine, swap aarch64-apple-darwin for x86_64-apple-darwin (Intel Mac), x86_64-unknown-linux-gnu or aarch64-unknown-linux-gnu.

npm install modebox and pip install modebox (Python 3.10 or later) install the library for your own code. They don't include the modebox command.

02 config

List your tools in modebox.json

Put it at your project root. Shell commands can only write inside that folder and temp folders.

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
    }
  },
  "approve": ["github.*"],
  "shell": { "enabled": true, "network": false, "allow": ["ls", "rg", "git status", "git diff"] },
  "limits": { "timeoutMs": 60000 }
}

mcpServers

Servers whose tools become functions, like github.create_issue(). Local (stdio) servers only.

approve

Patterns for calls that pause for your approval. * matches anything, so github.* asks before every GitHub call.

shell

Turns on sh(). Allowed commands run; anything else pauses. network is off, on, or a list of hosts.

flows · fetch · fs · limits

Data-flow rules, fetch(), file storage and resource limits.

mcp.approveTool

Whether to offer the approve tool. See approvals below.

Keep tokens out of the file. Your MCP servers inherit the environment your agent starts them with, so export GITHUB_PERSONAL_ACCESS_TOKEN=… there. Codex passes only a few variables, so its tab forwards the token with env_vars.

Check it before connecting anything:

03 connect

Connect your agent

Every agent runs the same command: modebox mcp.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "modebox": {
      "type": "local",
      "command": ["modebox", "mcp", "-c", "modebox.json"],
      "enabled": true,
      "timeout": 300000
    }
  },
  "permission": {
    "modebox_approve": "ask"
  }
}

{
  "mcpServers": {
    "modebox": { "command": "modebox", "args": ["mcp", "-c", "modebox.json"] }
  }
}

[mcp_servers.modebox]
command = "modebox"
args = ["mcp", "-c", "/absolute/path/to/your/project/modebox.json"]
env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]
tool_timeout_sec = 300

{
  "mcpServers": {
    "modebox": { "command": "modebox", "args": ["mcp", "-c", "${workspaceFolder}/modebox.json"] }
  }
}

04 approvals

How approvals reach you

modebox picks the best option your client supports.

MCP 2026-07-28 clients

The client asks you, and the paused run travels with the request, so your answer can come after a restart.

Clients that can prompt

You get a prompt inline, and the run continues.

Everyone else

The call is denied with a PermissionDenied error. "mcp": { "approveTool": true } offers an approve tool instead.

The model is the one that calls approve. Turn on approveTool only if your agent asks you before every call to it, and keep it off in any mode that skips permission prompts.

05 help

If something's off

The agent doesn't see modebox

Run modebox -c modebox.json types in the same folder. If that works, use the full path to modebox as the command.

Tool calls time out

Raise your agent's MCP timeout: timeout for opencode, tool_timeout_sec for Codex. Claude Code's default is already long.

A call was denied, not asked

Your client can't ask you itself, and approveTool is off.

sh() has no OS sandbox

On Linux, install bubblewrap and allow user namespaces. modebox never runs a command unconfined.

This guide in the repo