# Concepts

https://instabox.sh/docs/concepts.md

The few words the dashboard, the CLI and the API use.

| Word | What it is |
|---|---|
| **Machine** | A Linux VM of your own in the cloud, with its own kernel, root and Docker. Files under `/data` (home is `/data/home`) and the software you install stay. |
| **Template** | What a new machine starts from: `agent-browser` (the default), `universal`, `t3`, `herdr` or `orca`. The free plan creates from `agent-browser` or `ci` only. `instabox templates` lists them. |
| **Snapshot** | A saved copy of one of your machines, private to you. New machines can start from it. |
| **Operation** | A change to a machine (create, start, stop, pause, resume, delete). You follow it until it succeeds or fails. |
| **API key** | `ibk_...`: how programs, CI jobs and agents sign in. |
| **Org Secrets** | Encrypted credentials that sandboxes see as placeholders; the outbound proxy adds them to HTTPS headers for allowed hosts. |

### Running, paused, stopped
| State | Files | Memory and processes | Use it to |
|---|---|---|---|
| Running | kept | running | work |
| Paused | kept | kept | step away and come back to the same session |
| Stopped | kept | lost | shut down; the next start boots fresh |
| Deleted | gone | gone | free the machine for a new one |

A new machine pauses once it has been idle for 30 minutes. On a paid plan you can choose 5 to 30 minutes, or `instabox auto-suspend <machine> 0` to turn that off; below 5 or above 30 minutes is refused. On the free plan it stays 30 minutes, and `--auto-suspend` with another value is refused. Commands, files, SSH and a visit to one of its public port URLs resume it by themselves **only when it paused itself** (idle, the max-run cooldown or memory pressure: `autoSuspendedAt` set). A machine **you** paused or stopped stays offline: a public URL returns `503` (Sandbox offline) until you **Resume** (keeps memory) or **Start** (boots fresh).

> The API and CLI say `suspend`, `suspending` and `suspended` for pause, Pausing and Paused, and `error` for Failed.