instabox-mcp

A Model Context Protocol server for InstaBox: disposable cloud Linux machines for AI agents. It wraps the InstaBox REST API (https://api.instabox.sh) in 30 tools and 6 slash-command prompts, so any MCP client (Claude, Codex, Antigravity, oh-my-pi, Cursor, ...) can create a machine, run commands and edit files in it, snapshot it, expose a port and delete it again.

Unofficial. This project is not affiliated with or endorsed by InstaBox.

Features

• Full machine lifecycle: create, start, stop, pause (suspend), resume, rename, delete.

• Run code: exec with a shell string or argv, working directory, env vars, stdin and timeout.

• Files: read files, list directories, write files (binary-safe).

• Snapshots: save a machine, create new machines from it, browse snapshot files.

• Networking: publish ports as public HTTPS URLs, create short-lived SSH tokens.

• Observability: CPU/memory metrics, per-machine usage, account limits.

• Org Secrets: inspect and select which Secrets a machine may use (values are never exposed).

• Safe by default: asynchronous operations are awaited for you, every lifecycle call is idempotent, deletes need explicit confirmation, and a read-only mode removes every mutating tool.

Related MCP server: termdesk

Requirements

• Node.js 18 or newer

• An InstaBox API key (dashboard, API keys). A key with machines:read|write|delete and images:read|write|delete covers every tool.

Install

git clone https://github.com/syrex1013/instabox-mcp.git
cd instabox-mcp
npm install --include=dev
npm run build

--include=dev matters if your shell sets NODE_ENV=production, because the TypeScript compiler is a dev dependency.

Check that your key works (read-only, creates nothing):

INSTABOX_API_KEY=ibk_... npm run live-test

Configure your MCP client

Replace /absolute/path/to/instabox-mcp with the clone location and ibk_... with your key.

Claude Code

claude mcp add instabox --scope user --env INSTABOX_API_KEY=ibk_... -- node /absolute/path/to/instabox-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "instabox": {
      "command": "node",
      "args": ["/absolute/path/to/instabox-mcp/dist/index.js"],
      "env": { "INSTABOX_API_KEY": "ibk_..." }
    }
  }
}

Codex

Add to ~/.codex/config.toml (or run codex mcp add instabox --env INSTABOX_API_KEY=ibk_... -- node /absolute/path/to/instabox-mcp/dist/index.js):

[mcp_servers.instabox]
command = "node"
args = ["/absolute/path/to/instabox-mcp/dist/index.js"]
startup_timeout_sec = 30

[mcp_servers.instabox.env]
INSTABOX_API_KEY = "ibk_..."

Antigravity (agy)

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "instabox": {
      "command": "node",
      "args": ["/absolute/path/to/instabox-mcp/dist/index.js"],
      "env": { "INSTABOX_API_KEY": "ibk_..." }
    }
  }
}

oh-my-pi (omp)

Add to ~/.omp/agent/mcp.json:

{
  "mcpServers": {
    "instabox": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/instabox-mcp/dist/index.js"],
      "env": { "INSTABOX_API_KEY": "ibk_..." }
    }
  }
}

Config files are plain text. Keep them out of version control and use a restricted key where you can.

Configuration

Tools

Example prompts: "Create a machine, clone this repo into it and run the tests", "Snapshot my dev machine, then start a fresh one from the snapshot", "Publish port 3000 on dev and give me the URL".

Slash commands (prompts)

Clients that support MCP prompts expose these as commands. In Claude Code they appear as /mcp__instabox__<name>.

How it behaves

• Operations. Create, start, stop, suspend, resume and delete are asynchronous in the API. The tools long-poll GET /v1/operations/{id} until the operation finishes; pass wait: false to get the operation back immediately.

• Idempotency. Calls that need an Idempotency-Key get a fresh UUID, reused across automatic retries of that call. exec and SSH-token creation take none, so they are never retried after a response was received.

• Delete confirmation. instabox_delete_machine and instabox_delete_snapshot require confirm set to the exact ID or name and forward it as X-Confirm-Delete; the server rejects a mismatch with 409.

• Tool annotations mark read, write and destructive tools so clients can ask for approval accordingly.

• Errors include the API error code, hint, request ID and required scopes, and network failures include the underlying cause.

Security

• instabox_exec runs arbitrary code in a machine. Published ports are reachable by anyone with the URL, SSH tokens work for anyone holding them, and selecting org Secrets lets code in the machine send them to their allowed hosts.

• For machines that run untrusted code, create them with vault: false and no secrets / envSecrets.

• Use a restricted key, or set INSTABOX_READ_ONLY=true, when the model should only observe.

• Org Secret values cannot be created, read or changed with an API key; this server only reads metadata and manages per-machine selections.

Testing

scripts/live-test.mjs drives the built server over stdio against the real API:

INSTABOX_API_KEY=ibk_... node scripts/live-test.mjs dist/index.js <phase>

Not covered

Desktop/VNC control, SSH certificates (/connections), Vault items, file upload URLs and org/billing management are not exposed. Everything inside a machine can still be done with instabox_exec.

Development

npm run dev       # tsc --watch
npm run inspect   # open the server in the MCP Inspector

License

MIT