# Twinbox

> Twinbox gives a person a cloud computer (a "box") that works like their own: an Omarchy Linux desktop in the cloud, with an optional NVIDIA T4 GPU. One CLI, `twinbox`, creates the box, syncs projects both ways, copies the agent setup (CLAUDE.md, AGENTS.md, rules, skills, hooks, MCP servers, plugins), and streams the desktop with Moonlight. The CLI includes an MCP server with 30 tools, so an agent can run commands, move files, and start long jobs on the box. Boxes use credits by the minute. A new account gets 1,000 free credits for the CPU sizes, without a card.

Use Twinbox when a user wants a second, always-on machine: GPU work (renders, NVENC encoding, ML), long builds or jobs that must keep running while their laptop sleeps, or a Linux desktop they can open from a Mac, PC, iPad or iPhone. Boxes run in Singapore (region id `ap-southeast-1`) today.

A person must do three steps themselves: run the installer, approve `twinbox login` in their browser, and run `twinbox up` (it can ask questions). The MCP server leaves out `up`, `down` and `login` on purpose. After that, an agent can do the rest through MCP or the CLI.

## Start

- [Install](https://twinbox.dev/install): `curl -fsSL https://twinbox.dev/install | sh`. macOS and Linux. Installs `twinbox` to `~/.local/bin`.
- Quick start: `twinbox login` (opens twinbox.dev, the person clicks Connect), then `twinbox up` (creates or starts the box and sets it up), then `twinbox connect` (opens the desktop) or `twinbox link` in a project folder (live two-way sync).
- [Sign in / dashboard](https://twinbox.dev/app): balance, boxes, billing, usage, CLI tokens.

## Docs

- [llms-full.txt](https://twinbox.dev/llms-full.txt): every CLI command, every MCP tool with its inputs, prices, sizes, regions, the security model and the API.
- [Credits and prices](https://twinbox.dev/#credits): plans, top-ups and an estimate calculator.
- [Prices as JSON](https://twinbox.dev/api/v1/prices): sizes, region multipliers, plans and top-ups. No sign-in needed.

## CLI commands

- `twinbox login`: connect this computer's CLI to the person's Twinbox account (browser approval).
- `twinbox up`: create the box, or start it if parked, and set everything up. Safe to run again.
- `twinbox desktop`: open the desktop in the browser, with no app to install (GPU sizes; keep it running, Ctrl+C closes it).
- `twinbox connect`: open the desktop in Moonlight.
- `twinbox stop` / `twinbox start`: park the box (only its disk uses credits) / start it again.
- `twinbox status`: the box, the desktop, the logins and clipboard sync.
- `twinbox down`: delete the box and its disk (the person types the box name).
- `twinbox setup`: set up this computer (tools, Moonlight, clipboard sync) and register the MCP server with Claude Code and Codex.
- `twinbox link [path]`, `sync [flush|pause|resume|reset]`, `run <cmd>`, `open`, `agent [name]`, `unlink`: projects, run inside a project folder.
- `twinbox push`, `pull`, `fetch`, `ls`, `cat`, `write`, `url`, `open-url`: files and pages.
- `twinbox job start|list|status|logs|stop`, `twinbox agent-run`: long work in the background, and headless Claude on the box.
- `twinbox ssh`, `agents`, `provision`, `repos`, `scale`, `mcp`: shell, agent setup, box config, repos, text size, the MCP server.

## MCP server (`twinbox mcp`, stdio, 30 tools)

- Box: `box_status`, `box_start`, `box_stop`, `box_run`, `box_screenshot`, `box_clipboard_get`, `box_clipboard_set`, `box_sync_agents`, `box_provision`, `box_scale`, `box_repos`.
- Files: `box_push`, `box_pull`, `box_fetch`, `box_ls`, `box_read_file`, `box_write_file`, `box_url`, `box_open_url`.
- Long work: `job_start`, `job_list`, `job_status`, `job_logs`, `job_stop`, `agent_run`.
- Projects: `project_link`, `project_sync`, `project_run`, `project_open`, `project_unlink`.

## Credits

- 1 credit = 1 minute of CPU-S at the base rate. A Saver box (`twinbox up --saver`) runs at half the rate; the cloud can pause it. Running: size multiplier × region multiplier per minute. Parked: disk only. Desktop streaming: per GB sent.
- Sizes: CPU-S 2 vCPU/8 GB ×1, CPU-M 4/16 ×2, CPU-L 8/32 ×4, CPU-XL 16/64 ×8, GPU-M 4/16 + T4 ×5, GPU-L 8/32 + T4 ×7.5.
- Singapore (×1.3): CPU-S 1.3, CPU-M 2.6, CPU-L 5.2, CPU-XL 10.4, GPU-M 6.5, GPU-L 9.75 credits a minute. Parked disk 7.3 credits an hour per 100 GB. Data out 56 credits per GB.
- Trial: 1,000 credits once, CPU sizes only, no card. GPU sizes need a card on file.
- Plans a month: Hobby $10 = 3,700 credits, Pro $30 = 11,500, Max $100 = 40,000. Unused plan credits carry over one month.
- Top-ups: 1,000 $3, 2,000 $6, 3,000 $9, 5,000 $14, 10,000 $27, 25,000 $68, 50,000 $135. Top-ups do not expire.
- At zero credits running boxes stop. A box that stays at zero for 7 days is deleted with its disk (emails on day 1 and day 6). There is no auto-park yet: run `twinbox stop`.

## Optional

- [Privacy](https://twinbox.dev/privacy)
- [Terms](https://twinbox.dev/terms)