Use cases
End-to-end walkthroughs for reaching a goal with Cubicle Boxes, such as giving an AI agent a virtual machine to run code in, running CI jobs in a fresh Box per run and setting up remote development environments for a team.
Each use case walks through one goal from start to finish: why a Box fits it, a working setup, and what Cubicle cannot do for it. The walkthroughs are built on the how-to guides, and link to them and to Concepts for the detail of each step.
| If you are… | Start with | What Cubicle gives you |
|---|---|---|
| Building an AI agent that runs code | Give an AI agent a Box | A virtual machine with its own kernel for each task, while the API key stays in your program. Commands take a timeout, an output limit and an idempotency key, so a retried tool call returns the first run's result instead of running again. |
| Running CI or scripted jobs | Run CI jobs in Boxes | A fresh virtual machine for each run, from a base image or a template snapshot, driven with a service account API key, with no runner to install in the Box. Deleting the Box removes its disk and releases its resources. |
| Setting up development environments for a team | Remote development environments | A Box with a persistent disk for each developer, reached with ssh, VS Code or Cursor Remote-SSH and the private network. Per-Box grants decide which teammate can use which Box, and the Dashboard opens its desktop in the browser. |
Give an AI agent a Box
Build a run_command tool that runs an LLM agent's shell commands in its own Box for each task.
Run CI jobs in Boxes
Run tests in a fresh Box from GitHub Actions or a shell script, and delete it afterwards.
Remote development environments
Give each developer a Box they reach over SSH, from their editor and over the private network.
To do a single task, such as running a command, taking a snapshot or opening an SSH session, see the how-to guides.
Sign in and API keys
How people sign in to Cubicle (email and password, Google, cubicle login device flow) and reset a password, how programs authenticate with service account API keys (cbk_), which routes read and write keys can call, how to create, expire, revoke and use keys, and what happens to Boxes when a key, service account or member is removed.
Give an AI agent a Box
Give an LLM agent a Cubicle Box as its sandbox with @cubicle/sdk, with a framework-neutral run_command tool covering sh -c, timeoutMs, maxOutputBytes, truncated and timedOut results, exit codes, wake, idempotency keys, one Box per task, cleanup in finally, rate limits and what API keys cannot do.