Concepts
Computers, sessions and jobs: the three objects Modem is built on.
Computer
A computer is a micro-VM with a persistent disk, attached to your account. It has a name, a URL, an access token, and a state.
| State | What it means | What it costs |
|---|---|---|
running | Something is attached, or a job is working. | Active hours. |
suspended | Idle. Memory frozen, disk intact. | Disk only. |
What survives on the disk: your files and repositories, everything you installed, your agent and GitHub logins, shell history, caches, and the screens of detached sessions.
Sleeping and waking
A computer suspends a few minutes after the last activity: no attached session, no running job. Any command wakes it, typically in under a second. You never start or stop it by hand; if a command seems slow on its first call, that is the machine waking, and the CLI waits it out.
Session
A session is an interactive agent or shell running on the computer, inside a terminal multiplexer. modem claude creates one: or reattaches to the one that already exists for this folder.
Detaching with Ctrl+Q kills only the network connection. The session, its screen and its process stay on the machine. Reattaching redraws exactly what you left, from any machine you have set up.
Sessions are named after the folder you launch from, so the same project always comes back to the same screen.
Job
A job is one instruction executed headless by an agent, with a mandatory timeout. It has an identifier, a status, a log, and it survives your disconnection: this is what makes close your laptop true.
| Status | Meaning |
|---|---|
running | Working. Keeps the computer awake. |
completed | Finished on its own, exit code 0. |
failed | Finished with an error. |
stopped | You called modem stop. |
timed_out | Hit its limit and was killed. |
Because nobody is watching a headless job, the agent runs without permission prompts. The safety comes from the box, not from questions: an isolated VM, an unprivileged user, a hard timeout, no access to your laptop.
How they fit together
your terminal
│ modem claude ─────────────▶ session ┐
│ modem run "…" ────────────▶ job ├── on your computer
│ modem push / pull ────────▶ files ┘
▼
one machine, persistent, asleep when unusedOne computer per project is the natural unit. Parallelism between projects means several computers: a deliberate act, never a side effect.