Skip to main content
Glama

instabox-mcp

License: MIT Node 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: agent-vm-mcp

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

Variable

Default

Meaning

INSTABOX_API_KEY

required

ibk_... key, sent as X-API-Key

INSTABOX_API_URL

https://api.instabox.sh

API base URL

INSTABOX_READ_ONLY

off

true registers only the read-only tools

INSTABOX_MAX_OUTPUT_CHARS

60000

Cap on text returned per tool call

Tools

Area

Tools

Account

instabox_whoami, instabox_list_templates, instabox_get_usage

Machines

instabox_list_machines, instabox_get_machine, instabox_create_machine, instabox_update_machine, instabox_machine_power (start / stop / suspend / resume), instabox_delete_machine, instabox_get_operation, instabox_get_machine_metrics, instabox_get_machine_usage

Commands and files

instabox_exec, instabox_list_files, instabox_write_file

Snapshots

instabox_list_snapshots, instabox_get_snapshot, instabox_list_snapshot_files, instabox_create_snapshot, instabox_delete_snapshot

Public ports

instabox_list_ports, instabox_publish_port, instabox_unpublish_port

SSH

instabox_create_ssh_token, instabox_list_ssh_tokens, instabox_revoke_ssh_tokens

Org Secrets

instabox_list_org_secrets, instabox_get_machine_secrets, instabox_update_machine_secrets, instabox_refresh_machine_secrets

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>.

Command

Arguments

What it does

status

none

Account, limits, machines, snapshots and ports, with anything that looks wrong

run

machine, command

Run a shell command on a machine and show stdout, stderr and exit code

new-sandbox

name, template, lifetime_minutes, setup (all optional)

Create a self-deleting machine and optionally run a setup command

expose

machine, port

Check something listens, then publish the port as a public URL

backup

machine, name (optional)

Snapshot a machine and wait until it is ready

cleanup

none

List idle machines and snapshots and propose deletions, without deleting anything

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>

Phase

What it does

read

Account, templates, usage, machine / snapshot / port listings. Changes nothing.

lifecycle

Creates a throwaway machine (auto-deleted after 15 min), exercises exec, files, ports, power states, then deletes it. Needs a free machine slot.

existing

Non-destructive checks (exec, files, metrics, usage, secrets, delete-guard) on MACHINE_ID.

existing-write

Adds reversible writes on MACHINE_ID: a temp file, a port publish / unpublish, an SSH token, suspend / resume.

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

M8ven Verified

Available Tools

30 tools
instabox_create_machineCreate a machineA

Create a Linux machine (Firecracker microVM, Debian, root, Docker, 20 GiB persistent /data; home is /data/home) from a template or one of your snapshots. Starts as an asynchronous operation; by default this waits until the machine is running. Give templateId OR snapshotId (neither: agent-browser). Leave size fields out for the default 4 vCPU / 8 GiB; other sizes must be ones your plan allows (see instabox_whoami allowedSpecs). Counts against your machine limit even when stopped or paused.

Inputs: name, wait, vault, vcpus, +11 more.

instabox_create_snapshotSave a snapshot of a machineA

Save a machine as a private snapshot, then start new machines from it with instabox_create_machine snapshotId. A stopped machine is saved at once; a running one is saved live (if the server allows) and the snapshot is pending until uploaded; data programs had not yet written to disk is not included. By default this waits until the snapshot is ready. Counts against your snapshot and storage limits. Needs images:write.

Inputs: id (required), name (required), wait, rootOnly, +2 more.

instabox_create_ssh_tokenCreate an SSH tokenA

Create a ready-to-run ssh command for a machine (no key or CLI needed). SECURITY: the token is a secret; anyone holding it can log in to the machine until it expires or is revoked, and it is shown only in this response. Prefer a short ttl. Not idempotent: each call makes another token.

Inputs: id (required), name, ttlSeconds.

instabox_delete_machineDelete a machineA
Destructive

PERMANENTLY delete a machine and its disks (snapshots saved from it are kept). Cannot be undone. To guard against deleting the wrong machine, confirm must be the machine's exact ID or name; the server rejects anything else with 409 delete_confirmation_required. Needs the machines:delete scope.

Inputs: id (required), confirm (required), wait, waitTimeoutSeconds.

instabox_delete_snapshotDelete a snapshotA
Destructive

PERMANENTLY delete a snapshot. Machines already created from it are not affected. confirm must be the snapshot's exact ID or name (server-checked). Needs images:delete.

Inputs: id (required), confirm (required).

instabox_execRun a command in a machineA
Destructive

Run a command inside a RUNNING machine and return stdout, stderr and the exit code once it exits (a non-zero exit is still a normal result). Output is collected, not streamed, and each stream is cut at 1 MiB. Give cmd (a shell string, run with bash -lc) OR argv (program + arguments, no shell, no expansion). Runs as the machine's user in /data/home by default. Max 600 s per call: for long jobs start them in the background (e.g. nohup … > /data/home/job.log 2>&1 &) and poll the log. Not idempotent: a retry runs the command again. A machine paused for idleness is woken first; a machine you stopped returns 409 machine_not_running. This executes arbitrary code with root-capable access in the machine.

Inputs: id (required), cmd, cwd, argv, +3 more.

instabox_get_machineGet a machineA
Read-onlyIdempotent

Get one machine by ID or name: state (creating, starting, running, stopping, stopped, suspending, suspended = paused, resuming, deleting, error), spec, template, auto-pause setting, labels, guest user and whether its runtime is ready.

Inputs: id (required).

instabox_get_machine_metricsGet machine metricsA
Read-onlyIdempotent

CPU and memory samples (one per 30 s, oldest first) measured on the host for a machine. Empty while the machine is not running; a new machine's first sample appears after ~90 s. Default window is the last 5 minutes, at most 24 h back.

Inputs: id (required), since.

instabox_get_machine_secretsInspect a machine's SecretsA
Read-onlyIdempotent

Show which org Secrets a machine has selected and the delivery status of the outbound proxy and the guest environment (metadata only).

Inputs: id (required).

instabox_get_machine_usageGet machine usageA
Read-onlyIdempotent

Resource usage of one machine over a window (running seconds, vCPU-seconds, GiB-seconds of memory and disk), for billing or cost checks. Defaults to the current UTC month; the window may span at most 366 days. Works for deleted machines too (by ID).

Inputs: id (required), to, from.

instabox_get_operationGet an operationA
Read-onlyIdempotent

Get the status of an operation (create, start, stop, suspend, resume, delete) returned by a lifecycle call: state queued, running, succeeded or failed, plus phase and error. With waitSeconds it long-polls until the operation changes or finishes.

Inputs: id (required), waitSeconds.

instabox_get_snapshotGet a snapshotA
Read-onlyIdempotent

Get one snapshot by ID. status is ready (usable), pending (a live snapshot still uploading) or failed (see error).

Inputs: id (required).

instabox_get_usageGet account usage and limitsA
Read-onlyIdempotent

Account-wide counts of machines and snapshots, stored data (measured about hourly) and plan limits (max machines, snapshots, storage). Check this before creating machines when you may be near a limit.

Inputs: no named parameters.

instabox_list_filesRead a file or list a directory in a machineA
Read-onlyIdempotent

List a directory (up to 5000 entries, directories first) or read a text file (up to 256 KiB) from a machine, live and as root. Binary files come back with binary: true and no content. Use instabox_exec for larger files. The machine must be running (an idle-paused one is woken).

Inputs: id (required), path.

instabox_list_machinesList machinesA
Read-onlyIdempotent

List your machines (any state except deleted), one page at a time. Optionally filter by metadata labels. Returns nextCursor; pass it back as cursor for the next page.

Inputs: limit, cursor, metadata.

instabox_list_org_secretsList org Secret metadataA
Read-onlyIdempotent

List the names, delivery mode (proxy or env), allowed hosts and versions of an org's Secrets. Values are never returned. Get the org ID from instabox_whoami or a machine's orgId.

Inputs: orgId (required).

instabox_list_portsList public portsA
Read-onlyIdempotent

List published ports (public HTTPS URLs) of one machine, or of all your machines when id is omitted.

Inputs: id.

instabox_list_snapshot_filesBrowse a snapshot's filesA
Read-onlyIdempotent

List a directory or read a text file from a snapshot's installed software without starting a machine. Files under /data are not shown.

Inputs: id (required), path.

instabox_list_snapshotsList snapshotsA
Read-onlyIdempotent

List your snapshots, oldest first. A snapshot is a saved copy of a machine's software and /data files (not memory or processes); new machines can start from it.

Inputs: no named parameters.

instabox_list_ssh_tokensList SSH tokensA
Read-onlyIdempotent

List a machine's SSH tokens (newest first), without their secrets.

Inputs: id (required).

instabox_list_templatesList templatesA
Read-onlyIdempotent

List the templates a machine can start from (e.g. agent-browser, universal, herdr, orca) with their software and default size. Only templates with creatable: true can be used; the free plan can create from agent-browser only. Needs machines:read or images:read.

Inputs: no named parameters.

instabox_machine_powerStart, stop, pause or resume a machineA

Change a machine's power state. start: boot a stopped machine (resumes a paused one). stop: shut down; processes end, files kept (a paused machine cannot be stopped: resume or delete it). suspend: pause, keeping memory and running processes. resume: continue a paused machine where it left off. A machine runs one operation at a time (409 operation_conflict otherwise). Commands, files and SSH wake an idle-paused machine automatically, but a machine you paused or stopped stays off until you start/resume it.

Inputs: id (required), action (required), wait, stopTimeoutSeconds, +1 more.

instabox_publish_portPublish a portA

Give a port of a machine a public HTTPS URL. WARNING: the URL is not secret; anyone who has it can reach the whole service on that port until you unpublish it. It does not start a server. A visit wakes an idle-paused machine. Max 16 per machine, ports 1024-65535. Publishing again keeps the URL and renames it.

Inputs: id (required), port (required), name.

instabox_refresh_machine_secretsRefresh a machine's Secret deliveryA

Push the current Secret selection to a RUNNING machine now (installs the environment and CA, requests proxy reconciliation). Check the returned proxy and guest statuses.

Inputs: id (required).

instabox_revoke_ssh_tokensRevoke SSH tokensA
Destructive

Revoke one SSH token (give tokenId) or every token of the machine (omit it), closing their connections.

Inputs: id (required), tokenId.

instabox_unpublish_portUnpublish a portA

Remove a port's public URL and close its open connections. The server inside the machine keeps running.

Inputs: id (required), port (required).

instabox_update_machineUpdate a machineA

Change a machine's idle auto-pause time and/or labels. Applies immediately in any state. metadata REPLACES all labels ({} clears them). Fields you leave out are unchanged. Auto-pause is only honoured on accounts with manual lifecycle; the reply shows the effective value.

Inputs: id (required), name, metadata, autoSuspendAfterSeconds.

instabox_update_machine_secretsChange a machine's Secret selectionA

Replace the org Secrets a machine may use. Each field you pass replaces that whole selection; omitted fields stay as they are. SECURITY: secrets lets code in the machine send those credentials to their allowed hosts, and envSecrets puts real values into the machine. Delivery then updates in the background; refresh with instabox_refresh_machine_secrets.

Inputs: id (required), secrets, envSecrets.

instabox_whoamiWho am IA
Read-onlyIdempotent

Show which user/org the configured API key belongs to, including allowedSpecs (machine sizes this account may create) and lifecycle policy. Any key may call this, so it is the cheapest way to check that credentials work.

Inputs: no named parameters.

instabox_write_fileWrite a file in a machineA

Create or replace a file inside a RUNNING machine, creating parent directories. Implemented over exec (base64 on stdin), so it is limited to about 700 KB of content; for bigger files use instabox_exec with curl/git inside the machine. Overwrites without asking. Relative paths start at /data/home.

Inputs: id (required), path (required), content (required), mode, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 30 tools

    Disambiguation4/5

    Each tool targets a fairly specific resource+action, and descriptions explicitly distinguish the closest pairs (e.g. account-wide instabox_get_usage vs per-machine instabox_get_machine_usage vs instabox_get_machine_metrics; live instabox_list_files vs instabox_list_snapshot_files). The remaining overlap is mild but real: usage vs metrics vs whoami's plan limits all report capacity-ish data, and a naive agent could still pick the wrong granularity.

    Naming Consistency4/5

    The dominant pattern is a consistent instabox_verb_noun scheme (create_machine, list_snapshots, revoke_ssh_tokens, update_machine_secrets), which makes the set easy to scan. A few outliers break it: instabox_machine_power uses noun-first ordering, instabox_whoami is a bare phrase, and instabox_exec is a verb with no object.

    Tool Count3/5

    30 tools is on the heavy side, but the server genuinely spans seven sub-domains (machines, operations, metrics/usage, files/exec, snapshots, ports, SSH tokens, secrets), each covered by roughly 3-5 tools. It is defensible breadth rather than padding, though a few read-only lookups could be merged into their parent get_* responses.

    Completeness4/5

    Lifecycle coverage is strong: full CRUD plus power control for machines, full snapshot CRUD with file inspection, complete SSH token and port publish/unpublish flows, and a secrets selection/delivery flow with an explicit reconciliation call. Minor gaps exist — there is no file delete/rename (must fall back to instabox_exec), no get_port for a single published port, and no org-level secret creation/update, only listing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables managing Akamai Cloud (Linode) Compute Instances via MCP, with tools to list, create, view, update, delete, boot, reboot, shutdown, resize, and clone VMs. Each connecting client brings its own Linode Personal Access Token, which is passed through without being stored.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Provides an MCP control plane for a dedicated Linux VM, enabling shell-equivalent command execution, bounded filesystem and Git workspace operations, persistent process and coding-agent orchestration, artifact presentation, and optional upstream MCP bridge re-exports.
      27
      1
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables workspace-authorized creation and operation of isolated Firecracker microVMs over MCP or HTTP, letting users execute commands in full Debian guests, manage VM lifecycle, and transfer files without affecting the host process.
      1
      Apache 2.0