AgentBox

AgentBox runs coding agents in disposable boxes and manages the workspace, the file sync, and the services around them. The CreateOS plugin adds a provider, so those boxes become Firecracker microVMs instead of the built-in cloud options.

It is an add-on rather than a change to AgentBox. You install AgentBox normally, register the plugin, and then pick CreateOS per box.

At a glance

Package: @nodeops-createos/agentbox
Requires: AgentBox with provider plugin support, Node 20.10 or newer
Auth: a CreateOS API key, prompted on first use
Default box: 2 vCPU, 2 GB memory, 20 GB disk
Pause and resume: native, with an inactivity timeout

Set it up in four lines.

npm install -g @madarco/agentbox
npm install -g @nodeops-createos/agentbox
agentbox plugin add @nodeops-createos/agentbox
agentbox create --provider createos

The first line is AgentBox itself; the plugin does not bring it with it. plugin add asks you to confirm, then reports the provider as createos. The first box prompts for your API key. Get one at createos.sh/app/profile.

Install, register the provider, create a box, pause it, wake it and destroy it

On a machine that has never run AgentBox, the first command opens AgentBox's own setup. It asks which provider you want to set up and lists only AgentBox's built-in ones, so CreateOS is not there yet. Escape cancels the command you ran rather than skipping the question, and every interactive command reopens it until that setup is finished once.

Either finish it once with a provider you already have, or take the terminal out of the equation for these two commands:

agentbox plugin add @nodeops-createos/agentbox < /dev/null
agentbox create --provider createos < /dev/null

AgentBox only asks when it is attached to a terminal, so redirecting input skips it and the command runs normally.

The first create in a new folder also asks whether to run its in-box setup, which writes an agentbox.yaml and installs the project's dependencies. Answer No if you just want a box.

Prerequisites

You need an AgentBox install new enough to load provider plugins. agentbox plugin list should show the plugin once it is added; if that command does not exist, AgentBox needs updating first.

Unlike most integrations on this page, this one does not use the createos CLI. It calls the control-plane API directly and reaches into the box over an authenticated websocket, so createos login does nothing for it and the CLI is not a prerequisite.

Giving it your key

Three ways, in the order the plugin looks:

Where	When to use it
The prompt on first `create`	Normal interactive use
`CREATEOS_API_KEY` in the environment	CI and scripts
`~/.agentbox/secrets.env`	Keeping it out of your shell history

CREATEOS_SANDBOX_URL points the plugin at a different control plane, which you only need for a non-default endpoint.

There are two further names the plugin accepts but does not advertise, AGENTBOX_CREATEOS_API_KEY and AGENTBOX_CREATEOS_API_URL. They behave the same as the two above and exist for people who prefix every variable by tool.

Using it

Pick the provider per command:

agentbox create --provider createos
agentbox codex --provider createos

Everything after that is ordinary AgentBox. The workspace sync, the relay, the service supervision and the lifecycle all behave the way they do with the built-in providers, because the plugin implements the same contract rather than replacing anything.

An optional check confirms your key and the runtime assets before you rely on it:

agentbox prepare --provider createos

This step is optional here, which is unusual. See Why there is no prepare step.

What you get

Public preview URLs for services running in the box
A remote desktop over VNC
Docker inside the box, so containerized workflows still work
Workspace resync and a direct git mode
Orphan pruning, so abandoned boxes do not accumulate quietly

Interactive sessions attach over CreateOS's authenticated websocket shell. There is no SSH key to manage and no CLI in the path, which is one fewer thing to install and one fewer credential to place.

Pause and resume

agentbox pause <box> pauses a box, and an inactivity timeout pauses one that has been left alone. A paused box keeps its disk and costs nothing to hold, so the usual pattern is to leave a box paused between sessions rather than destroying and rebuilding it.

There is no resume command. A paused box comes back when you next use it, so reattach or start an agent against it rather than looking for a way to wake it first.

Pausing is not instant: it takes around two minutes, because the box is archived rather than merely suspended. Waking one takes about fifteen seconds. Neither blocks anything else you are doing.

Two things it cannot do

No checkpoints. AgentBox can checkpoint a box on some providers. CreateOS has no matching snapshot feature yet, so the plugin reports checkpoints as unsupported rather than faking them. Nothing else about the provider depends on this.

Why there is no prepare step

On other providers, agentbox prepare bakes the AgentBox runtime into a reusable image so later boxes start faster. CreateOS cannot currently build that image from a local runtime, so every box installs the runtime while it provisions instead.

The practical effect is that the first command in a fresh box waits for that install, and there is no preparation step you are required to run first. The optional prepare above only validates your credentials.