This page needs JavaScript. For agents, the same site as Markdown: https://instabox.sh/llms.txt (below), every page at its URL plus .md.
# InstaBox
> InstaBox gives each agent a Linux machine of its own in the cloud. Start with one command, then read only the page you need.
## Key facts
- API base URL: https://api.instabox.sh. Every body is JSON. Lifecycle calls (create, start, stop, suspend, resume, delete) and the other endpoints that list it need an `Idempotency-Key` header (any unique string); `exec` and Secrets take none. Deleting a machine or snapshot also takes an optional `X-Confirm-Delete` header, its ID or exact name: any other value is `409 delete_confirmation_required` and nothing is deleted.
- Exec: `POST /v1/machines/{id}/exec` takes `cmd` (a shell string, run with `bash -lc`) or `argv` (a program and its arguments, run with no shell), not both: `{"argv": ["printf", "%s|", "a b", "$X"]}` prints `a b|$X|`.
- Auth: send an API key (`ibk_...`) as `X-API-Key: <key>` or `Authorization: Bearer <key>`, for example `curl -H "X-API-Key: $INSTABOX_API_KEY" https://api.instabox.sh/v1/machines`. Create one in the dashboard (**API keys**) or with `instabox keys create --name N`; the CLI uses `INSTABOX_API_KEY` from the environment. A missing or unknown key gets `401 unauthenticated`. Details: https://instabox.sh/docs/api.md
- Quick start: `npx instabox@latest sh`, or `curl -fsSL https://api.instabox.sh/install.sh | sh` for the `instabox` CLI.
- Default template: `agent-browser` (Debian, Docker, Node.js, Python, Go, Rust, a desktop and Chromium); the free plan creates from it only (or from a snapshot). `universal` is the same without the desktop preinstalled.
- Machine: a Firecracker microVM, Debian 13 (trixie) amd64, kernel 6.18.54, 4 vCPUs / 8 GiB by default, a 16 GiB root disk (8 GiB on `herdr` and `orca`) and a 20 GiB persistent disk at `/data` (home is `/data/home`). Python 3.13 with `python3 -m venv` and pip on every template. Per-template specs: the Machine specs table in Limits.
- Sizes (vCPU/GiB): Free 4/8 only; Pro 2/4, 4/8, 8/16; Team 2/4 up to 32/64. `GET /v1/orgs` (`instabox workspace ls --json`) lists each workspace's as `allowedSpecs`.
- Plan limits: Free 1 machine, 5 snapshots, idle pause fixed at 30 min. Pro 500 machines, 100 running. Team unlimited machines, 500 running. Paid plans choose the idle time (5-30 min) or turn it off.
- Plans: Free $0, Pro $20/month + usage, Team $500/month + usage, Enterprise Custom.
- Usage prices: vCPU $0.004 per vCPU-hour, Memory $0.00225 per GiB-hour, Storage $0.00011 per GiB-hour, Egress $0.02 per GiB. Runtime is billed per second, only while running. Details: https://instabox.sh/docs/pricing.md
## CLI cheat sheet
```
instabox login sign in with a device code (or set INSTABOX_API_KEY)
instabox templates list templates
instabox create --name N [--template T | --snapshot S]
instabox create --name N --setup-file PATH then run a script in it (at most 64 KB)
instabox ls [--json] your machines
instabox get <machine> [--json]
instabox exec <machine> -- <cmd...> run one command; exits with its code
instabox ssh <machine> a shell over SSH
instabox files <machine> [PATH] list a directory or print a file
instabox suspend|resume <machine> pause and resume, memory kept
instabox stop|start|rm <machine>
instabox restart <machine> power-cycle a hung machine (stop, start), disks kept
instabox auto-suspend <machine> 10m|0 idle time before pause (0: off, paid plans)
instabox snapshot save <machine> --name N then create --snapshot N
instabox fork <machine> [--count N] snapshot + create, snapshot deleted after
instabox port publish <machine> <port> a public HTTPS URL for a port
instabox port-forward <machine> <port> a private localhost tunnel until Ctrl-C (or LOCAL:REMOTE)
instabox keys create --name N an API key, printed once
instabox usage counts and limits
```
Each page below is Markdown. The same page for people is at the URL without .md. Every page in one file: https://instabox.sh/llms-full.txt
## Get started
- [Quick start](https://instabox.sh/docs/start.md): From nothing to a shell in your own cloud machine.
- [Concepts](https://instabox.sh/docs/concepts.md): The few words the dashboard, the CLI and the API use.
- [Integrate with the SDK](https://instabox.sh/docs/integrate.md): The calls an app needs: create, pause and resume, delete, a shell, the desktop, and usage.
## Guides
- [Machines](https://instabox.sh/docs/machines.md): Lifecycle, auto-pause, labels and secrets.
- [Snapshots](https://instabox.sh/docs/snapshots.md): Save a machine once, start new ones from it.
- [Connecting over SSH](https://instabox.sh/docs/ssh.md): With the CLI, or one ssh line for any terminal.
- [Public ports](https://instabox.sh/docs/ports.md): Give a web server in a machine an HTTPS URL.
- [Desktop: see it and control it](https://instabox.sh/docs/desktop.md): Watch a machine's desktop, let an agent drive it, and share a link to it.
- [Org Secrets](https://instabox.sh/docs/secrets.md): Credentials added to HTTPS headers by the outbound proxy, scoped to your org.
- [API keys and SDK](https://instabox.sh/docs/keys-sdk.md): Drive machines from code: TypeScript, HTTP, or the CLI with a key.
## Reference
- [SDK reference](https://instabox.sh/docs/sdk.md): Every class, method and option of @insforge/instabox-sdk.
- [CLI reference](https://instabox.sh/docs/cli.md): Every command. Add --help to any of them for the details.
- [Pricing](https://instabox.sh/docs/pricing.md): Plans, what each includes, and the unit prices of usage.
- [Limits](https://instabox.sh/docs/limits.md): What each plan allows, and the machine specs. Account and GET /v1/usage show yours.
## API reference
- [API overview](https://instabox.sh/docs/api.md): Authentication, operations, idempotency and errors: what every endpoint shares.
- [Machines](https://instabox.sh/docs/api/machines.md): Create, list, change and delete machines.
- [Lifecycle](https://instabox.sh/docs/api/lifecycle.md): Start, stop, pause and resume machines.
- [Commands and files](https://instabox.sh/docs/api/commands.md): Run a command in a machine and read its files.
- [Snapshots](https://instabox.sh/docs/api/snapshots.md): Save a machine, then start new machines from it.
- [Operations](https://instabox.sh/docs/api/operations.md): Follow a change to a machine until it is done.
- [SSH](https://instabox.sh/docs/api/ssh.md): Log in to a machine with ssh or mosh.
- [Public ports](https://instabox.sh/docs/api/ports.md): Give a web server in a machine an HTTPS URL.
- [Secrets](https://instabox.sh/docs/api/secrets.md): Org credentials, sandbox selections and delivery status.
- [Account](https://instabox.sh/docs/api/account.md): Templates, your usage and limits, and who a key belongs to.
## Optional
- [OpenAPI document](https://api.instabox.sh/v1/openapi.json): every endpoint an API key calls, as OpenAPI 3.1 JSON