instabox-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@instabox-mcp create a fresh Linux machine and run npm test in it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
execwith 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|deleteandimages:read|write|deletecovers 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-testConfigure 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.jsClaude 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 |
| required |
|
|
| API base URL |
| off |
|
|
| Cap on text returned per tool call |
Tools
Area | Tools |
Account |
|
Machines |
|
Commands and files |
|
Snapshots |
|
Public ports |
|
SSH |
|
Org 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 |
| none | Account, limits, machines, snapshots and ports, with anything that looks wrong |
|
| Run a shell command on a machine and show stdout, stderr and exit code |
|
| Create a self-deleting machine and optionally run a setup command |
|
| Check something listens, then publish the port as a public URL |
|
| Snapshot a machine and wait until it is ready |
| 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; passwait: falseto get the operation back immediately.Idempotency. Calls that need an
Idempotency-Keyget a fresh UUID, reused across automatic retries of that call.execand SSH-token creation take none, so they are never retried after a response was received.Delete confirmation.
instabox_delete_machineandinstabox_delete_snapshotrequireconfirmset to the exact ID or name and forward it asX-Confirm-Delete; the server rejects a mismatch with409.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_execruns 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: falseand nosecrets/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 |
| Account, templates, usage, machine / snapshot / port listings. Changes nothing. |
| Creates a throwaway machine (auto-deleted after 15 min), exercises exec, files, ports, power states, then deletes it. Needs a free machine slot. |
| Non-destructive checks (exec, files, metrics, usage, secrets, delete-guard) on |
| Adds reversible writes on |
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 InspectorLicense
Available Tools
30 toolsinstabox_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 machineADestructive
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 snapshotADestructive
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 machineADestructive
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 machineARead-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 metricsARead-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 SecretsARead-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 usageARead-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 operationARead-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 snapshotARead-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 limitsARead-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 machineARead-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 machinesARead-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 metadataARead-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 portsARead-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 filesARead-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 snapshotsARead-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 tokensARead-onlyIdempotent
List a machine's SSH tokens (newest first), without their secrets.
Inputs: id (required).
instabox_list_templatesList templatesARead-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 tokensADestructive
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 IARead-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
Scored across 30 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP for Celesto cloud computers: create, exec, ports, start/stop/delete.
Start, pause, resume, and run commands and file operations in Linux sandboxes.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Manage Sprites: sandboxed compute environments with exec, services, and checkpoints.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables 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.-
- AlicenseBqualityBmaintenanceProvides 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.271ISC
- AlicenseNot gradedqualityBmaintenanceEnables managing multiple Linux SSH servers from MCP clients, with structured filesystem operations, shell commands, durable long-running jobs, process listing, and CPU/RAM/disk/GPU status.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1Apache 2.0