AgentBox provider plugin: run agent boxes on CreateOS Sandbox

AgentBox provider plugin: run agent boxes on CreateOS Sandbox

To run AgentBox boxes on CreateOS, install AgentBox, install and register the CreateOS provider plugin, then run agentbox create --provider createos. The first box asks for your CreateOS API key. Each box is then a Firecracker microVM with its own guest kernel, and the rest of AgentBox works as usual.

AgentBox runs coding agents in disposable boxes and manages their workspace, file sync and services. CreateOS Sandbox supplies the machine underneath: its own kernel, root filesystem and network identity per box.

AgentBox is an open-source project at github.com/madarco/agentbox. The CreateOS provider plugin is maintained by CreateOS and is not a product of the AgentBox project.

Key takeaways

• The CreateOS provider is a plugin: a separate npm package you install and register with agentbox plugin add. AgentBox does not ship it.
• Once registered, --provider createos turns a box into a microVM with its own guest kernel.
• The plugin talks to the CreateOS API directly, so you do not need the createos CLI or createos login.
• The plugin creates every box with an allow-all egress rule. Outbound traffic stays open until you replace that rule.

What is the AgentBox provider plugin for CreateOS?

It is an add-on that gives AgentBox a new provider called createos. AgentBox ships seven built-in providers and lets anyone publish more as plugins, each its own npm package, with no changes to AgentBox itself (AgentBox provider plugins guide). The CreateOS plugin is one of those packages.

Per the CreateOS docs for AgentBox, workspace sync, the relay, service supervision and the box lifecycle behave as they do with the built-in providers. For background, read about cloud development environments for AI agents.

How do I set up the CreateOS provider in AgentBox?

Four steps take you from nothing to a first box. You need Node 20.10 or newer, a CreateOS account and an AgentBox install new enough to load provider plugins (see Prerequisites).

Step 1: How do I install AgentBox?

Install AgentBox itself first, because the plugin does not bring it with it:

npm install -g @madarco/agentbox

Step 2: How do I install and register the CreateOS plugin?

Install the plugin package, then register it with agentbox plugin add. Copy both commands from the setup block at the top of the CreateOS docs for AgentBox. plugin add asks you to confirm, then reports the provider as createos.

Check that it loaded with agentbox plugin list. If that command does not exist, update AgentBox before you go further. Without this step, step 3 fails: AgentBox has no createos provider until the plugin is registered.

Step 3: How do I create my first box?

Pick the provider on the command:

agentbox create --provider createos

The first box prompts for your API key. A first create in a new folder also offers AgentBox's in-box setup, which installs project dependencies. Answer No if you only want a box.

Step 4: How do I pause a box between sessions?

Run agentbox pause <box>. A paused box keeps its disk. An inactivity timeout also pauses a box that has been left alone. There is no resume command: a paused box comes back when you next use it, so reattach or start an agent against it (Pause and resume).

Why does AgentBox not show CreateOS on first run?

A fresh AgentBox install opens its own provider setup, which lists only the built-in providers. Escape cancels the command you ran, and every interactive command reopens the setup until it is finished once. Either finish it with a provider you already have, or redirect input so AgentBox skips the question:

agentbox create --provider createos < /dev/null

Do the same for plugin add. AgentBox only asks when attached to a terminal.

How do I give the plugin my API key?

The plugin looks in three places, in this order: the prompt on first create, CREATEOS_API_KEY in the environment for CI and scripts, and ~/.agentbox/secrets.env to keep the key out of your shell history (Giving it your key).

agentbox prepare --provider createos is optional. It only checks your key and the runtime assets. Each box installs the AgentBox runtime while it provisions, so the first command in a fresh box waits for that install.

Can an AgentBox box on CreateOS reach the internet?

Yes. The plugin creates every box with egress set to ["*"], which allows all outbound traffic. On CreateOS, an empty rule list or ["*"] means open egress. Once you set any other rule, the box becomes deny-by-default: only listed destinations pass, and everything else is dropped in-kernel on the host, outside the VM, where code inside the box cannot change it (Limits and defaults).

AgentBox has no egress option for this provider. To lock a box down, replace its allowlist with PUT /v1/sandboxes/{id}/egress. Rules apply live, with no restart. For why the kernel boundary matters, read when a coding agent needs a microVM.

What are the limits of the CreateOS provider for AgentBox?

The main limits are the account box cap, the default size and the missing checkpoint support.

• Box cap. Your account caps how many boxes exist at once and how many you create per day. Paused boxes count, and only destroying a box frees a slot. A create over the cap fails rather than queueing (concurrency limits).
• Default size. Each box gets 2 vCPU, 2 GB of memory and a 20 GB disk. Your account sets the largest shape and disk you can create. Pass a CreateOS shape slug or cpu-memory-disk in GB with --size, such as --size 1-1-10.
• No checkpoints. CreateOS has no matching snapshot feature for AgentBox checkpoints yet, so the plugin reports them as unsupported.
• Public preview URLs. The plugin turns on ingress for each box, so preview URLs for services in the box are public.
• Bandwidth. Each box gets a 50 GiB bandwidth budget by default, and it can be extended.
• No GPUs. No GPU shapes are offered.

Each box also gets a VNC desktop, Docker inside the box, and pruning of orphaned boxes.

When do I not need this?

If AgentBox's local Docker boxes or one of its built-in providers already fit your needs, skip this plugin. Use it when you want each box on CreateOS. For the wider picture, read what an AI agent sandbox is.

Common questions

Is CreateOS a built-in AgentBox provider?

No. CreateOS is a provider plugin, a separate npm package maintained by CreateOS. You install it, register it with agentbox plugin add, and then pick it per box with --provider createos.

Do I need the createos CLI to use AgentBox with CreateOS?

No. The plugin calls the CreateOS API directly and attaches to boxes over an authenticated websocket shell. createos login does nothing for it, and there is no SSH key to manage.

Why can agentbox create not find the createos provider?

The plugin is not registered yet. Install the plugin package and run agentbox plugin add, then confirm it with agentbox plugin list. If that command is missing, update AgentBox first.

How do I restrict outbound traffic from an AgentBox box on CreateOS?

The plugin creates boxes with egress open to all hosts. Replace the rule list through the CreateOS Egress API. Once any rule is set, only listed destinations pass and everything else is dropped on the host, outside the VM.

What happens to my files when an AgentBox box is paused?

A paused box keeps its disk. There is no resume command: the box comes back when you next use it, so reattach or start an agent against it. Run agentbox destroy when you no longer need a box, because paused boxes count against your account cap.

Does the CreateOS provider support AgentBox checkpoints?

No. CreateOS has no matching snapshot feature yet, so the plugin reports checkpoints as unsupported rather than faking them.

Next step

The docs page holds the two plugin commands and every option. Open the CreateOS provider docs for AgentBox, then create an API key in the CreateOS app and create your first box.

About CreateOS

CreateOS runs AI agents and the code they write. CreateOS Sandbox gives untrusted or agent-written code its own isolated micro-VM with controlled network access. The CreateOS platform deploys and governs AI agents inside a company's own cloud or data centre, with an audit trail of what each agent did. Start at createos.sh.