instabox 0.8.161 → 0.8.162
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/cli/SHA256SUMS +6 -6
- package/cli/instabox-darwin-amd64 +0 -0
- package/cli/instabox-darwin-arm64 +0 -0
- package/cli/instabox-linux-amd64 +0 -0
- package/cli/instabox-linux-arm64 +0 -0
- package/cli/instabox-windows-amd64.exe +0 -0
- package/cli/instabox-windows-arm64.exe +0 -0
- package/package.json +1 -1
- package/skills/instabox/SKILL.md +3 -3
- package/skills/instabox-snapshots/SKILL.md +1 -1
package/cli/SHA256SUMS
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
384a6c4641a761c4e17d55c61457c1fbddffcc8c8404044980e1153d573afbf5 instabox-darwin-amd64
|
|
2
|
+
a39a937eac3f0ce94439fa4f502f88cbf894b7676b592709b6f294b96e666741 instabox-darwin-arm64
|
|
3
|
+
1fda92b66a1c3ace6b4728ade25d7464777f0e462a938666772100bfbcfcdd69 instabox-linux-amd64
|
|
4
|
+
8c54f49a69b45372cd04ea93248cfa6742c71524ae780d825dcffb200079810e instabox-linux-arm64
|
|
5
|
+
fff803204c68f319c5718fe01249e1a48cbeb44b3a85caefd1119469a9c4aa1c instabox-windows-amd64.exe
|
|
6
|
+
80d37d47ecbd2573b57e910eea240b47cbdf64778591f4a43ebaf664bdf2f3c9 instabox-windows-arm64.exe
|
|
Binary file
|
|
Binary file
|
package/cli/instabox-linux-amd64
CHANGED
|
Binary file
|
package/cli/instabox-linux-arm64
CHANGED
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
package/skills/instabox/SKILL.md
CHANGED
|
@@ -90,7 +90,7 @@ instabox rm --yes work # delete the box (without --yes
|
|
|
90
90
|
- Max run minutes is independent of idle activity: `-1` is unlimited, `0` pauses immediately, and a positive integer forces a pause after that many running minutes. Free boxes have a fixed 480-minute cap that only an admin session can change; paid boxes default to `-1` and can change it. An idle override does not permit changes to a free box's runtime cap. The first limit reached pauses the box; both timers restart after sleep and wake.
|
|
91
91
|
- A runtime pause blocks every wake path during a server-configured cooldown, 5 to 20 minutes by default (`409 machine_cooldown` with `Retry-After`). On the free plan, back-to-back max-run pauses rest longer: 60 to 75 minutes for the 2nd in a row and 120 to 135 for later ones; the count starts over when a run ends with no cooldown owed (idle pause, a user pause or stop) or starts 2 hours or more after the last cooldown. A security lock (up to 24 h) is a cooldown too and keeps the count. Wait until the `cooldownUntil` deadline shown by `instabox get`; edits cannot clear it. Afterward, a box that paused itself (idle or runtime) wakes on `exec`, `ssh`, `files`, a public port request or `instabox wake <box>`. A box you paused (`instabox suspend`) or stopped does not wake on any of these, `wake` included: run `instabox resume <box>` or `instabox start <box>`. A zero runtime cap must be changed before waking. A normal pause preserves memory and processes.
|
|
92
92
|
- Kernel updates (a patched guest kernel, e.g. CVE-2026-98432 in 6.18.60): a box runs the new kernel from its next cold boot, files kept. Running box: `instabox restart <box>` (or `instabox stop <box> && instabox start <box>`). Stopped box: `instabox start <box>`. Paused box (suspend or idle auto-pause): `instabox resume <box> && instabox restart <box>`; a paused box refuses `stop` and `restart`, and `start` resumes it with the old kernel in memory. A `sudo reboot` inside a box that comes back by itself is a cold boot too. Resume alone is not. New boxes start on the new kernel, and so do boxes from a snapshot of a box whose template does not pin its kernel. Check with `uname -r` (`6.18.60-instabox`). Templates with a pinned kernel: `android` (`-instabox-android`) and `omarchy` (restricted access, `-instabox-drm`). Their boxes keep the kernel they were created with through all of the above, and boxes from their snapshots or forks keep it too. Create a new box from the template and copy your files across (`instabox pull`, then `push`). A kernel package installed inside the box changes nothing.
|
|
93
|
-
- `sudo reboot` inside a box
|
|
93
|
+
- `sudo reboot` (or `reboot -f`) inside a box boots it again by itself, in about 20 seconds: same disks, processes and `/tmp` gone. `instabox get` lags by up to 30 seconds, so `running` does not mean it is back: retry the next `exec` while it fails with `retryable: true` (`503 host_unavailable`, or `409` "machine is restarting"), and compare `cat /proc/sys/kernel/random/boot_id` to know it rebooted. Do not `start` or `restart` it meanwhile: `restart` on it does nothing and exits 75, and that 75 does not mean run `restart` again (once the box is back it would power-cycle it). `sudo poweroff`, `halt` or `shutdown -h` inside stops it until `instabox start`. Boxes from older template versions stop on `sudo reboot` too: start them. https://instabox.sh/docs/machines.md#rebooting-and-powering-off-from-inside-a-box
|
|
94
94
|
- If `exec`/`ssh` stop answering (hang or time out on a running box), run `instabox restart <box>` (alias `recover`; `--timeout 20s` shortens the wait, `--json` prints the box). It stops the box, killing the VM if it has not shut down by the timeout (60 seconds by default), then starts it and waits until it runs. Files on the root disk and `/data` stay; processes do not, so start your servers again. A paused box is not hung: resume it. A box stuck in `starting` with no start in progress cannot be restarted; restart says so.
|
|
95
95
|
- Disk full (`df -h /data`)? Grow it with `instabox resize <box> --disk N` (`/data`, where HOME is), in GB. A running box grows online, no restart. A shrink, a paused box, or an image that can't grow online needs `--restart` (it stops the box, resizes the disk and starts it again; files stay, processes do not), else resize changes nothing and says so. A shrink must fit your data plus 10% (at least 1 GB), else it's refused (`disk_too_small`) and nothing changes. Free-plan boxes keep their size. The system disk (`/`) is the template's; you can't grow it.
|
|
96
96
|
- Need more CPU or memory? A paid box moves to another of its plan's sizes with `instabox resize <box> --vcpus N --mem-mib M` (Pro: 2/4096, 4/8192, 8/16384; Builder: 2/4096 up to 16/32768; Team: 2/4096 up to 32/65536), while it is stopped; add `--restart` on a running box, and run that from outside the box (from inside, the stop would end the command before the start, so resize refuses it; the same goes for a shrink with `--restart`). A size the plan does not have is refused before anything stops. The new size applies at the next start; free-plan boxes keep theirs.
|
|
@@ -100,13 +100,13 @@ instabox rm --yes work # delete the box (without --yes
|
|
|
100
100
|
- 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; …`).
|
|
101
101
|
- `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.
|
|
102
102
|
- `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`).
|
|
103
|
-
- 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): the server copies `work`'s disks (running or stopped) on its host into `--count` boxes (1-5) with the same template and size and boots them, in a few seconds and with no snapshot (memory and running programs are not copied); with an older server that has no native fork, or with `--keep-snapshot`, it saves a snapshot, creates the boxes from it and deletes the snapshot, also on error or Ctrl-C, unless `--keep-snapshot`; a suspended box is copied neither way, so resume
|
|
103
|
+
- 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): the server copies `work`'s disks (running or stopped) on its host into `--count` boxes (1-5) with the same template and size and boots them, in a few seconds and with no snapshot (memory and running programs are not copied); with an older server that has no native fork, or with `--keep-snapshot`, it saves a snapshot, creates the boxes from it and deletes the snapshot, also on error or Ctrl-C, unless `--keep-snapshot`; a suspended box is copied neither way, so resume it first. `work` is not changed. Several boxes are named `N-1` to `N-N`; 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, native, snapshotId, snapshotName, kept, snapshotMs, createMs, totalMs}` (`native` true: no snapshot was used).
|
|
104
104
|
- `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`; past 1 MiB the CLI uploads it as a file first). A CLI built before 2026-10-26 refuses stdin past 1 MiB (`stdin is larger than 1048576 bytes`): run `instabox update` instead of splitting the input. A big file can also go in with `push`, then exec reads it: `instabox push work bundle.tgz /tmp/` and `instabox exec work -- tar -xzf /tmp/bundle.tgz -C /data/workspace`. push checks the SHA-256 and sends a file of 64 MiB or more as parallel parts by itself; past 5 GiB, `split` the file, push the parts, and `cat` them together in the box. `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.
|
|
105
105
|
- 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).
|
|
106
106
|
- To hand a task to a coding agent inside the box, use `instabox agent`: `instabox agent prompt work [--provider claude|codex] [--model M] [--new | --resume ID] [--attach FILE] [--cwd D] [--env K=V] [-f] [--json] "text"` starts a turn as a background job (`claude -p --output-format stream-json` or `codex exec --json`, permission prompts and sandboxing skipped: the box is the boundary) and prints the conversation ID (`--json`: `{conversationId, turn, jobId, pid}`; `-f` follows the turn and exits with its code). `instabox agent events work [-c ID] [-f] [--json]` prints the conversation's events, one JSON object per line: the agent's own, between `instabox.turn` (with the prompt) and `instabox.turn_end` (`exitCode`, `interrupted`). `instabox agent steer work [-c ID] "text"` interrupts the running turn, if any, and resumes the agent's session with the text; `instabox agent interrupt work [-c ID]` stops the turn (INT, then TERM, then KILL); `instabox agent ls work [--json]` lists conversations (status `running`, `idle`, `interrupted`, `failed(N)` or `lost`). Without `-c`, the conversation prompted last. The agent needs its key in the box's environment: `ANTHROPIC_API_KEY` (or `CLAUDE_CODE_OAUTH_TOKEN`) for claude, `OPENAI_API_KEY` (or `CODEX_API_KEY`) for codex, from an org Secret the box selects, or `--env`; the CLI warns when none is set. When the template lacks the agent CLI, the first turn installs it with npm into `~/.instabox/agent-cli` (an `instabox.install` event), or fails with an `instabox.error` event when there is no npm. State lives in `~/.instabox/agents/<id>` in the box. A turn waiting on the model API looks idle to auto-suspend (network does not count), so keep `agent events -f` (or `prompt -f`) going for a long turn you need to finish.
|
|
107
107
|
- A box that does not boot, is unreachable, or failed to start or resume: `instabox logs work` prints its console log (kernel and systemd boot messages) and its last 20 operations with their errors, in any state, without waking it. Add `-f` to follow it or `--json` for `GET /v1/machines/{id}/logs`.
|
|
108
108
|
- Output: `--json` (or `-o json`) works on every command (each command's `-h` lists it); the only exceptions are `ssh`, `mosh` and `port-forward`, which are interactive and refuse it with the JSON error code `json_unsupported` (use `exec --json`). With JSON output a failure prints `{"error":{"code","message",...}}` on stdout instead of text on stderr and still exits non-zero (2 for usage errors, code `usage`); API errors keep the server's `code`, `status`, `requestId` and `retryable` (present when true). Piped, the list and status commands (`ls`, `get`, `templates`, `usage`, `snapshot ls`, `port ls`, `keys ls`, `secrets ls`, `vault ls`, `workspace ls|get|members|invites`) print JSON on their own, so `instabox ls | jq` works; `--output table` or `INSTABOX_NO_AUTO_JSON=1` keeps the table. `exec`, `ssh`, `files` and the other commands print the same output piped or not.
|
|
109
|
-
- Exit codes: a failed command exits 1 for any other error, 2 usage, 3 auth (not signed in, a bad or expired key, no permission: 401/403), 4 not found (404), 5 quota or plan limit (`quota_exceeded`, `credit_exhausted`, `spend_limit_reached`, `spec_not_allowed`, other 402/429), 75 retryable (`retryable: true`, such as `no_capacity` and `host_unavailable`, or another 5xx; retry with backoff). `--json` errors exit the same way. Commands that run something (`exec`, `ssh`, `jobs wait`, `output`, `run`, ...) exit with its code instead. Branch on the code (`case $? in 4) ...`), not on message text.
|
|
109
|
+
- Exit codes: a failed command exits 1 for any other error, 2 usage, 3 auth (not signed in, a bad or expired key, no permission: 401/403), 4 not found (404), 5 quota or plan limit (`quota_exceeded`, `credit_exhausted`, `spend_limit_reached`, `spec_not_allowed`, other 402/429), 75 retryable (`retryable: true`, such as `no_capacity` and `host_unavailable`, or another 5xx; retry with backoff; except `restart` on a box restarting itself after a reboot inside it: nothing to do, do not rerun `restart`). `--json` errors exit the same way. Commands that run something (`exec`, `ssh`, `jobs wait`, `output`, `run`, ...) exit with its code instead. Branch on the code (`case $? in 4) ...`), not on message text.
|
|
110
110
|
- The box's HOME has `MACHINE.md` (which box it is, its size, what survives a stop, the installed tools) and `AGENTS.md`, a moment after it starts. They are reference for when a task needs a fact about the box, not steps to run first.
|
|
111
111
|
- A public URL for a web server in the box: `instabox port publish work 3000` prints it (`instabox port ls`, `instabox port unpublish work 3000`). The URL works while the box runs. A request wakes a box that paused itself for being idle; a box you paused or stopped answers `503` (Sandbox offline) until you `instabox resume` or `instabox start` it.
|
|
112
112
|
- A raw TCP service (Postgres, Redis) reachable from anywhere, where the server enables it: `instabox port publish work 5432 --tcp` prints `5432-<id>.<tcp domain>:443`; clients connect with TLS and that host as SNI (`psql "host=<host> port=443 sslmode=require user=postgres"`). Otherwise, or for a private tunnel, use `instabox port-forward work 5432`.
|
|
@@ -42,7 +42,7 @@ This reads the snapshot's root disk only; `/data` (and HOME) are not browsable h
|
|
|
42
42
|
|
|
43
43
|
## Copy a box
|
|
44
44
|
|
|
45
|
-
`instabox fork` does it in one command: it copies a running or stopped box into a new box (or `--count` up to 5, named `NAME-1` to `NAME-N`) with the same template and size and waits until it runs. The server copies the disks on the box's host and boots the copy in a few seconds, with no snapshot; memory and running programs are not copied. With an older server that has no native fork, or with `--keep-snapshot`, it goes through a snapshot (save, create, delete unless `--keep-snapshot`). A suspended box is copied neither way: resume
|
|
45
|
+
`instabox fork` does it in one command: it copies a running or stopped box into a new box (or `--count` up to 5, named `NAME-1` to `NAME-N`) with the same template and size and waits until it runs. The server copies the disks on the box's host and boots the copy in a few seconds, with no snapshot; memory and running programs are not copied. With an older server that has no native fork, or with `--keep-snapshot`, it goes through a snapshot (save, create, delete unless `--keep-snapshot`). A suspended box is copied neither way: resume it first. The source box is not changed.
|
|
46
46
|
|
|
47
47
|
```sh
|
|
48
48
|
instabox fork work --name work2
|