instabox 0.8.12 → 0.8.13

package/README.md

@@ -9,7 +9,7 @@ npx instabox@latest sh   # the same, then start a new box and SSH into it
 
 `npx instabox@latest sh` does all that, then starts a new box (`box-<hex>`) and drops you into it over SSH, no questions. Run by an agent (no terminal), it starts the box and prints `instabox ssh <box> -- <command>` instead of opening a shell. At the box limit it starts nothing and lists your boxes, to remove one (`instabox rm --yes <box>`) or open one (`instabox ssh <box>`).
 
-A GitHub and a Google sign-in are separate instabox accounts, each with its own boxes. Both this entry point and `instabox login` let the sign-in page offer both. `--google` asks for Google directly, as does `instabox login --provider google`.
+A GitHub and a Google sign-in are separate instabox accounts, each with its own boxes. Both this entry point and `instabox login` let the sign-in page offer both. `--google` asks for Google directly, as does `instabox login --provider google`. An agent with no browser and nobody at the keyboard signs itself up instead with `instabox login --agent` once the CLI is installed (docs/agent-auth.md): it prints a claim page and a code for the account owner, who approves later from any device.
 
 Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox)): `npx instabox@latest ls` runs `instabox ls`, installing the CLI first if it is missing.
 

package/cli/SHA256SUMS

@@ -1,6 +1,6 @@
-621146535ec57cfaa3b61b16830f1c75524f1d0eddde7ffcbcf738471c608b33  instabox-darwin-amd64
-3f8b98c1b0de4bc41010dda69b4690c6843ab54ddf7a8e78b186d9e2d056c98f  instabox-darwin-arm64
-1ef1447c0936aec924aa309615211981babbd071a01a171dfec879f2242a0904  instabox-linux-amd64
-13dbe2802a9956a608c0730919264f5d3b9adb5a496a60450d32f2c9b67af0b6  instabox-linux-arm64
-5fb2a4fe8146a66a866d70b76ef27d1f52b908bf39245fdc97b10fa91c25765c  instabox-windows-amd64.exe
-511eaf6bc2be0e44a02a81c431f394d075b3766c8916af0f8444b0741427cfab  instabox-windows-arm64.exe
+7d5350ab3623beac005443c08ebf5dca49a448602c205a7c202ee0ad34bbe526  instabox-darwin-amd64
+54cbe5be166a80dfca298257c2de73783d2db987873c92af9bd4a3f76c929517  instabox-darwin-arm64
+57df92cb0443d8a3f755741efad60376f20aeee954b916364409138828b0e48f  instabox-linux-amd64
+e0cb19b167f5f228eac8f1ca21ce59c435ab8c7fd1e0b9cbc660283bf0937655  instabox-linux-arm64
+70f0bc3f9ac2eeb9bcb9ebb14d5a7ad6ce4000b0c3b3ee423a2d4c6e4572914e  instabox-windows-amd64.exe
+b918aa14919e508725b4cf9171113189eb5cac6adecc0d6f6d0e8cd722d706e2  instabox-windows-arm64.exe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "A cloud box for your coding agent, the instabox CLI and its agent skills in one command: npx instabox@latest",
   "type": "module",
   "bin": {

package/skills/instabox/SKILL.md

@@ -22,6 +22,8 @@ A GitHub sign-in and a Google sign-in with the same verified email share one acc
 
 For CI or an agent without a browser, use an API key instead: `export INSTABOX_API_KEY=ibk_...` (the user creates it in the dashboard: API keys in the sidebar). Never print, commit or log a key.
 
+With no key and nobody at the keyboard, sign up by yourself: `instabox login --agent` (optionally `--name 'what this agent is' --scope machines:read,machines:write --expires-in-days 30`). It prints a claim page (`https://dashboard.instabox.sh/dashboard/claim?code=XXXX-XXXX`) and the code; relay both to the user and wait. The user opens the page on any device, signs in or signs up, checks what you ask for and approves; the command then finishes on its own, stores the API key made for you in the user's account, and every later `instabox` command uses it. The code works for 24 hours. If you must do other work meanwhile, `instabox login --agent --no-wait` prints the page and code and exits, and `instabox login --agent` later resumes the same registration. Before the user approves you have no account and no credential: do not retry other commands, wait. A denial or an expired code is an error; register again only if the user asks. The user can also approve from their own terminal with `instabox claim XXXX-XXXX`.
+
 ## Templates
 
 `agent-browser` is the default, so `create` needs no `--template` for ordinary work. It is Debian 13 (trixie, amd64, kernel 6.18.54) with git, gh, Node.js 22 (npm, pnpm, Yarn), Bun, Python 3.13 (`python3 -m venv`, pip, uv), Go, Rust, a C toolchain, Docker, Claude Code and Codex, plus a desktop (VNC, Chromium) ready for browsing or driving a GUI from the start, on a 16 GiB root disk and a 20 GiB persistent disk at `/data`. The dashboard shows it as **standard**. Pick another template only for its one purpose:
@@ -56,7 +58,9 @@ instabox ssh work                               # interactive shell (leave with:
 instabox exec work -- uname -a                  # one command, no SSH client needed
 instabox exec work --cwd /data/home -- ls -la   # exec runs `bash -lc` as the box's user
 instabox run -- make -v                         # one-shot: new box, run, delete it, exit with the code
-instabox ps work                                # its processes: pid, ppid, user, %cpu, %mem, elapsed, command
+instabox ps work                                # its processes: pid, ppid, user, %cpu, %mem, elapsed, command (a stopped box: the list from just before its stop)
+instabox history work                           # the commands run in it through exec, newest first, with exit codes (stopped boxes too)
+instabox output work                            # the last command's stored output (or: instabox output work ex_<id>)
 instabox files work /data/home                  # list a directory (or print a text file)
 instabox push work ./app                        # copy a file or directory in (to /data/home/app)
 instabox pull work /data/home/app/out.log       # copy a file or directory out (to ./out.log)
@@ -72,6 +76,7 @@ instabox rm --yes work                          # delete the box (without --yes
 ```
 
 - Names or IDs (`m_...`) both work wherever `<id-or-name>` is accepted.
+- For large uploads use `instabox push` or `instabox cp` (the HTTP API, parallel-friendly), not scp or rsync over `ssh.instabox.sh`, which keeps about 2 MiB in flight per connection and so slows with distance. Measured: at a 5 ms round trip both paths do ~104 MB/s; at 305 ms the API does 11-13 MB/s per stream and SSH 3-6 MB/s; 4 parallel API PUTs did 39 MB/s total.
 - `create` options: `--template T` or `--snapshot S`, `--vcpus N --mem-mib M` (a size of the plan, see Sizes), `--auto-suspend D|0`, `--max-run-minutes N`, `--delete-after D` (delete it D after creation, 1m-24h, whatever its state), `--meta K=V`, `--org O`, `--secrets all|NAME,NAME|none`, `--no-wait`, `--setup-file PATH|-` (`--wait-setup`), `--fail-fast` (when no host has room, fail at once and create nothing instead of failing the create after; with `--snapshot`, instead of creating it stopped).
 - `create --setup-file PATH` (`-`: stdin; at most 64 KB) runs that script in the new box once it is running, in HOME as the box's user (by its `#!` line, else with bash; CRLF line endings become LF), and prints its output; it replaces create + push + exec for provisioning. A failing script makes `create` exit with the script's code and keeps the box: debug it with `instabox exec work -- /tmp/instabox-setup.sh`. With `--json` the sandbox object gets a `setup` object (`exitCode`, `stdout`, `stderr`, `signal`, `timedOut`, `truncated`, `durationMs`). `create` always waits for the script (`--wait-setup` names that; `=false` is refused) and keeps its state in the box's metadata, so `instabox get work --json` shows it later: `metadata.setupStatus` (`pending`, `running`, `succeeded`, `failed`), `setupExitCode` (`124`: timed out) and `setupLog` (the last 512 characters of its stdout then stderr). The script is killed after `--setup-timeout` (default and at most 10m); for longer installs, use `ssh`. A missing, empty or over-64 KB file is refused before any box is created. `run --setup-file` does the same before its command, with its `-e` variables; when the script fails, run's `--json` `exitCode` is the script's. The script stays at `/tmp/instabox-setup.sh` (and in snapshots), so keep credentials out of it.
 - Idle auto-pause defaults to 30 minutes. Paid boxes allow 5, 10, 15, 20, 25 or 30 minutes (a time between rounds up; below 5m or above 30m is refused, nothing created), or `0` to turn it off. Free boxes keep 30 minutes unless an admin grants an idle override; asking another value on a free box fails (`permission_denied`, nothing created), so leave `--auto-suspend` out there. Idle means no agent working, no terminal use and little CPU.
@@ -85,7 +90,8 @@ instabox rm --yes work                          # delete the box (without --yes
 - Use `cp`, `push` and `pull` to move files, not `echo <base64> | base64 -d` over `exec`. `cp LOCAL work:PATH` and `cp work:PATH LOCAL` copy either way (`-r` for directories). `push work LOCAL [REMOTE]` copies a file or directory to REMOTE (default: HOME); an existing directory or a path ending in `/` receives it under its own name. REMOTE's parent directory must exist (else `missing_parent`); `-p` creates it. A file streams byte-for-byte, up to 5 GiB, and its sha256 is checked; a directory goes as a gzipped tar of at most 1 GiB. From inside a git repo, a directory push sends only tracked files (`git ls-files -c`); `--all` adds untracked files git does not ignore; `node_modules`, build output and `.git` stay behind. `pull work REMOTE [LOCAL]` copies back the same way: a file streams, any size; a directory is read as root, at most 32 MiB compressed. Over HTTP: `PUT /v1/machines/{id}/files?path=P` with the raw body, `GET /v1/machines/{id}/files/content?path=P`, and `POST /v1/machines/{id}/files/upload-url` for a signed URL that takes the PUT without a key.
 - `exec` with one argument after `--` runs it as a shell string (`instabox exec work -- 'ls | wc -l'`); several arguments run as that exact argv, each quoted for you (`instabox exec work -- bash -c 'echo a b > /tmp/x'`).
 - For a one-off job that needs no box afterwards, use `instabox run [--template T | --from SNAPSHOT] [--name N] [--push DIR] [--cwd D] [-e K=V ...] [--timeout 60s] [--keep] [--setup-file PATH|-] [--json] -- <cmd...>` instead of create + exec + rm: it deletes the box even when the command fails or the run is interrupted (Ctrl-C, SIGTERM), and exits with the command's code (124: timed out). Its own failures have their own codes: 2 usage, 75 `--fail-fast` and no host has room (retry later), 125 `run` itself failed (API, network, create, upload or cleanup), 130 interrupted; with `--json` they print the `{"error": {...}}` object, except a failed cleanup delete: the result then has `deleted: false` and `cleanup: {"error": {...}}` (stdout is always one JSON document). One argument is a shell string, several an exact argv. The same 10-minute limit as `exec` applies. `--push .` first uploads the current directory's files (those git does not ignore) into the working directory (`--cwd`, default HOME), so `instabox run --push . -- 'go test ./...'` tests your checkout. `--name N` is used as is (1-63 lowercase letters, digits or `-`, starting with a letter or digit; default `run-<8 hex digits>`). A box left behind by a killed CLI is deleted by the server at its `deleteAt`, 5 minutes after its timeout (10 with `--push`, plus another timeout with `--setup-file`); a cleanup delete that gets a 5xx, a retryable error or no answer is retried 5 times with backoff. `--setup-file PATH|-` runs a setup script (at most 64 KB) first, in HOME with the same `--timeout` and `-e` variables (after `--push`); if it fails, `run` exits with its code without running the command. `--keep` keeps the box with no deadline and, once it was created, prints `Kept NAME; delete it with: instabox rm --yes NAME` to stderr (stdout stays the command's; `--json` has it as `sandbox`); a failed create operation prints only its error (one whose wait was cut short is kept, with `Kept NAME, whose create had not finished; …`).
-- `instabox ps work [--all] [--json]` lists the processes running in the box (it runs `ps` through exec, so it wakes a box that paused itself and refuses a stopped or manually paused one). Kernel threads and the listing's own processes (its shell, `ps`, `head` and the sshd sessions exec uses) are left out unless `--all`. `--json` prints an array of `{pid, ppid, user, cpuPercent, memPercent, elapsedSeconds, command}`: `instabox ps work --json | jq '.[] | select(.command | test("node"))'`. It lists only what runs now; there is no history of past commands or their output.
+- `instabox ps work [--all] [--json]` lists the processes running in the box (the server runs `ps` through exec, so it wakes a box that paused itself). Kernel threads and the listing's own processes (its shell, `ps`, `head` and the sshd sessions exec uses) are left out unless `--all`. `--json` prints an array of `{pid, ppid, user, cpuPercent, memPercent, elapsedSeconds, command}`: `instabox ps work --json | jq '.[] | select(.command | test("node"))'`. A stopped or manually paused box shows the list the server read just before it stopped or paused (a stderr note says when it is from), so you can see what was running when a box went down; a box that was never listed while running says so and asks you to start it.
+- `instabox history work [--limit N] [--json]` lists the commands run in the box through `exec` (by anyone: the CLI, the API, other agents; not SSH sessions), newest first, with ID, start time, duration and exit code, also while the box is stopped. The server keeps the newest 200 with the first 64 KiB of each output stream. `instabox output work [ex_<id>]` prints a past command's stored stdout and stderr (the last command's by default) and exits with its exit code, as `exec` did; `--json` gives `{id, command, cwd, startedAt, durationMs, status, exitCode, stdout, stderr, ...}`. Use them to find out what an earlier session or another agent ran in a box and what it printed, instead of rerunning it. The `jobs` polls and `ps` are not recorded; `exec --background` is recorded as `exec --background: <cmd>` (its output is in `jobs logs`).
 - To copy a box (try something risky, or run agents side by side from the same state), use `instabox fork work [--name N] [--count N] [--keep-snapshot] [--json]` (`clone` works too): it saves a snapshot of `work` (live while it runs, where the server allows), creates `--count` boxes (1-5) from it with the same template and size, waits until they run, and deletes the snapshot, also on error or Ctrl-C, unless `--keep-snapshot`. `work` is not changed. Several boxes are named `N-1` to `N-N`. It is snapshot + create, so it takes about as long as those two; each box counts toward the plan's starts a minute, which fork waits out (up to 5 minutes in total). If the source's size is no longer one of the plan's sizes, pass `--vcpus N --mem-mib M`. On a failure part-way it prints which boxes were created; they are kept, so delete those you do not need. `--json` prints `{source, machines, snapshotId, snapshotName, kept, snapshotMs, createMs, totalMs}`.
 - `exec` returns the command's exit code and takes `--stdin` to pipe input (any size up to 5 GiB, binary too: `instabox exec work --stdin -- tar -xz -C /data/workspace < src.tgz`). `exec --json` prints one object instead of the raw output (`stdout`, `stderr`, `exitCode`, `signal`, `timedOut`, `truncated`, `invalidUtf8`, `durationMs`) and still exits with the command's code: `instabox exec work --json -- make test | jq .exitCode`. exec output is UTF-8 text: each stream is cut at 1 MiB (`truncated`; `--stream` has no cap) and bytes that are not UTF-8 become U+FFFD (`invalidUtf8`), so never copy a file out with `exec -- cat` (an APK or tarball comes back corrupt); use `pull`/`cp`. A cut is noted on stderr and keeps the exit code; when the command exits 0 but its output was binary, exec says so on stderr and exits 65 (its own code, like 75 and 125, so it never looks like the command's). `exec --stream` prints the output as the command writes it instead of at the end (same timeout and exit code; with `--json`, one `{"type":"stdout"|"stderr","data"}` object per line, then `{"type":"exit","exitCode",...}`), so you can watch a build or test run as it goes. It stops the command after `--timeout` seconds: 60 by default, 600 at most (whole seconds; `run`'s also takes `90s` or `5m`). A larger or unparsable value is a one-line usage error, exit 2. It returns when the command exits, even if it left a process running in the background (`instabox exec work -- 'nohup ./server >server.log 2>&1 &'` returns at once and the server keeps running); background output written later than about a second after the exit is not returned, and a background process that still writes to exec's stdout or stderr after that gets a broken pipe (it may die, or a server may drop requests), so send both to a file (`>log 2>&1`) or use `exec --background`. Run longer commands (installs, builds, test suites) over SSH, which also returns the exit code: `instabox ssh work -- 'cd /data/workspace/app && npm ci'`. The box's runtime cap still applies during SSH or exec.
 - For work past 600 s, or to keep going while you do something else, start a background job: `instabox exec --background work -- 'npm run build'` prints a job ID at once (`--json`: `{jobId, pid}`); then `instabox jobs ls work`, `instabox jobs logs work <job> -f` (streams until it ends, exits with its code; Ctrl-C leaves the job running), `instabox jobs wait work <job> [--timeout 30m]` and `instabox jobs kill work <job> [--signal KILL]` (the whole process group). This is the CLI polling over plain exec calls. A job holds no activity lease: only its CPU use, or a running `jobs wait`/`logs -f`, counts as activity, so keep `jobs wait` going for a quiet job you need to finish. A pause freezes the job and it carries on after resume; a stop ends jobs (`exited(143)`, or `lost` after a hard stop).