BoxCI

What it is

BoxCI turns InstaBox VMs into dedicated GitHub Actions runners for your repository. One command plans the setup, a local workflow diff wires up CI, and your jobs run on machines you control.

Already have CI? boxci migrate moves your existing jobs onto the pool, Blacksmith or ubuntu-latest alike, as a local diff you review. It ships with an agent skill, so your coding agent can do the migration with you.

Pick jobs that run on Linux x64 and whose steps work on both the InstaBox VM and the hosted Ubuntu fallback.

Get started

1. Install the CLI with npm install -g @balasivagn/boxci, then run boxci --help to list commands.
2. Initialize from your app's checkout with boxci init. It reuses your GitHub and InstaBox sign-ins, shows the plan for your approval, then sets up the runner. Workflow changes stay local.
3. Migrate existing CI with boxci migrate. Select the workflow jobs to move onto the pool, then review and approve the local diff.

cd /path/to/your-app
boxci init --dry-run
boxci init
boxci migrate

Then review, commit, and push the workflow changes through your usual process. BoxCI creates no branch or PR.

Why BoxCI

• Bring your existing CI. boxci migrate retargets the jobs you already have (Blacksmith runs-on labels, for example) as a local diff you review and commit.
• Agent-ready. The bundled boxci-migrate skill teaches your coding agent to drive boxci migrate instead of hand-editing YAML.
• Reviewable. boxci init --dry-run shows what setup will create. The real run leaves workflow files locally for your review.
• Nothing extra to keep running. No keepalive, no webhook server, no BoxCI account. The wake step lives inside GitHub Actions.
• A dashboard that watches without touching. boxci dashboard is local, authenticated and read-only. It never wakes a VM.
• Hosted fallback built in. Fork PRs, or a pool that is not fully ready, run on hosted Ubuntu instead. Fork code never receives your provider key.

How it works

1. Wake. A hosted Ubuntu job reads the pool variable and CI secret. For a trusted event it wakes every pool VM at once and checks their runner services. This privileged step never checks out PR code.
2. Route. If the whole pool is ready, the build targets your dedicated self-hosted label. Otherwise, and always for fork PRs, it falls back to hosted ubuntu-24.04.
3. Run. GitHub assigns the build to an idle runner with matching labels. Afterwards the VMs keep InstaBox's normal idle suspension.

Commands

Run boxci --help to see every command and flag in your installed version.

Requirements

• Node.js ^22.19.0 || >=24.5.0 (22.19+ on 22.x, or 24.5+), npm, Git and access to GitHub. npm does not block installs on older Node; it only warns, and setup commands stop.
• A GitHub.com repository where you have admin access, with Actions enabled.
• An InstaBox account with capacity for at least one additional VM, or an existing verified CI pool.
• Use a dedicated InstaBox account for CI if you can. The CI key can execute commands on every VM in its account.

Good to know

• BoxCI is an early release. The current published version is shown on the npm package page.
• The CI credential expires every 30 days, with no automatic renewal or reminder. Renew it with boxci auth renew.
• BoxCI makes no cost or speed promises. InstaBox usage, the hosted wake and fallback jobs, and other services follow their own billing.
• BoxCI is an independent open-source integration. It is not built or endorsed by InstaBox, and it is not affiliated with boxci.dev.

Docs

• README: quick start, commands, migration and caveats
• Configuration: sign-in, local project records, repository settings, pool discovery
• Operations: status, renewal, adding capacity, recovery, troubleshooting, cleanup
• Architecture: setup, CI and monitoring paths, with a source map
• Validation: what is tested today and what still needs verification
• Security: credential scope and isolation limits