instabox (npm)

npx instabox@latest      # sign in, install the CLI and the agent skills
npx instabox@latest sh   # the same, then start a new box and SSH into it

npx instabox@latest signs you in to instabox in your browser (first run only; confirm its current Instabox account or choose another), installs the instabox CLI already signed in or updates an out-of-date one (skip with --no-cli), installs or updates the agent skills from ../skills in ~/.claude/skills and ~/.agents/skills (skip with --no-skills), and prints the next steps. It does not touch your boxes.

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 <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 browser confirm the account. Explicit --github or --google starts that provider directly, as does instabox login --provider github|google.

Any other command line is the instabox CLI's (cmd/instabox): npx instabox@latest ls runs instabox ls, installing the CLI first if it is missing.

How it works

• bin/instabox.mjs runs instabox's loopback sign-in (RFC 8252 + PKCE) and saves the tokens where the CLI keeps its own, ~/.config/instabox/credentials.json, so both are signed in at once. There is one copy on purpose: the server rotates refresh tokens and ends the session when a rotated one comes back.
• sh always starts a new box, with no timeout and no idle auto-suspend of its own. An existing box is entered with the CLI: instabox ssh <box>.
• An installed CLI is checked against what the server's /install.sh would install: the binary's sha256 against the server's /dl/SHA256SUMS (release builds are named after a commit, so their versions do not sort). One the server no longer serves is replaced in place through the same installer; a development build (instabox dev, or -dirty) is left alone with a one-line notice of the install command.
• Skills are written only over copies marked installed-by: instabox; the output says which were installed, updated, already up to date, or kept because they are the user's own.
• On Windows, where /install.sh does not run, the CLI is installed by lib/cli.mjs itself: /dl/instabox-windows-<arch>.exe, checked against SHA256SUMS and --version, renamed to %LOCALAPPDATA%\Programs\instabox\instabox.exe. The output gives the PowerShell line that puts that folder on the user's PATH; npx instabox@latest <command> finds it without that.
• The bin is also called instabox, so lib/cli.mjs finds the real CLI the way the insta CLI does: PATH without node_modules dirs and without links back to this script, then the installer's own targets.
• prepack copies ../skills into the package; every skill there ships on the next publish.

Develop

npm ci
npm test
npm run format:check
npm pack            # copies ../skills, then builds instabox-<version>.tgz
npx --package=./instabox-0.4.3.tgz instabox --help

INSTABOX_API_URL points it at another instabox server.

Release

Bump version in package.json and merge that to main. npm-release.yml publishes when the merged commit is the one that changed the version: it runs the tests, publishes through npm trusted publishing (so there is no npm token anywhere), then tags the commit npm-v<version>. Nothing to tag or push by hand, and anyone who can merge can release - npm maintainer access is not needed. A version with a - (0.5.0-rc.1) goes to the next dist-tag, never to latest. If a publish fails after its merge, re-run the workflow from the Actions tab; it does nothing when the version is already on the registry.

The trusted publisher is set on npmjs.com, package instabox → Settings → Trusted Publisher: GitHub Actions, InsForge / instabox / npm-release.yml. The very first publish, before the package existed, was by hand with npm publish --access public from this directory.