Sandbox hosts and deployment options

Every agent run in Disco Parrot happens inside a sandbox, and every sandbox runs on a host: the actual compute that holds the container. Most teams never think about it, because the default is managed and invisible. But where that compute lives is a real choice, and for a team with a security boundary, a data-residency rule, or a cluster it already runs, it is an important one. This page is the map of the options.

A host is what a sandbox profile points at. Choosing a host is how you put a particular kind of work on the compute it should run on, the same way choosing an image decides what is in the container. For the concept of what a sandbox is and why every run gets its own, read sandboxed execution; for how the platform itself deploys and how these hosts fit the overall architecture, see deployment and hosting; this page is about making the deployment choice.

The three ways to run a sandbox

There are three answers to "where does this run," and they trade setup for control in a straight line.

• Managed. Disco Parrot runs the sandbox for you on its own serverless compute, with nothing to install and no infrastructure to operate. This is the default.
• Bring your own Kubernetes. You install a small operator into a cluster you already run, and your cluster runs the sandboxes inside your boundary.
• Bring your own Docker. You run an operator on a Docker engine you control, the lightest way to keep runs on your own compute, and the only one that can hold a workspace between runs.

The thread through all three is that only the location of the compute changes. A sandbox on your Kubernetes cluster still comes up from the same managed image, with the same runtime, the same tools, and the same change policy as one on the managed host. Bringing your own host is not a different product or a stripped-down mode; it is the same environment, running where you want it to run. The platform and runtime reference lists the host kinds and the resource classes by their exact names.

How a profile chooses a host

A sandbox profile carries the choice on its General tab, and there are three shapes it can take:

• Managed, the default: the profile names no host, and the platform runs the sandbox on its managed compute.
• A specific host: the profile points at one registered host by name, so every sandbox from that profile lands on that exact cluster or engine.
• Your default Docker host: the profile points at "the Local Docker host I have set as mine," which resolves at launch to whichever host you personally registered. It is what lets a profile be shared across a team while each person's runs land on their own machine, which is the natural pattern for local development.

Because the host is a property of the profile, the decision is made once, by whoever owns the profile, and every launch inherits it. A planning profile can sit on the managed host where nobody runs infrastructure; a profile that has to keep agent work inside your network points at your cluster. The how-to for setting this is on sandbox profiles.

Managed: the default, with nothing to run

The managed option is the one you already have. With no host registered and no host named on a profile, the platform provisions the sandbox on its own compute and tears it down when the work is done. Your team operates no servers, patches no operators, and watches no clusters. For planning, for most coding work, and for anyone who just wants agents to work without standing up infrastructure, managed is the answer, and it is why the first run in a new workspace already works.

Bring your own Kubernetes

When agent runs need to live on infrastructure your organization owns, you register a Kubernetes host. You install a small operator into a cluster you already run (a managed AKS, EKS, or GKE cluster, or your own on-premises one), and that operator launches and tears down the sandboxes inside your boundary. It runs anywhere Kubernetes runs. The platform itself never calls your cluster's API. The operator reaches out to the platform, never the other way around, so there is no inbound port to open and no endpoint of yours exposed to the internet.

Inside the cluster, those sandboxes authenticate to your cloud resources as a workload identity rather than carrying a stored secret, so you get the platform's environment on your own infrastructure with no standing keys living in it.

Because the operator runs inside your cluster, it inherits your cluster's posture: your namespaces, your network policy, your node pools. A sandbox lands as a pod on compute you already govern, scheduled and torn down by the operator, so the agent run that would have happened on managed compute now happens under your admission controllers and your audit. Nothing about how the sandbox is built changes; only the scheduler that places it does. The full walkthrough, the operator bundle, the workload-identity prerequisites, the egress the operator needs, and how to check its health, is set up a BYO Kubernetes host.

Bring your own Docker

When you want runs on your own compute without standing up a cluster, you register a Local Docker host. An operator runs on a Docker engine you control, usually Docker Desktop, and launches sandboxes as containers on that engine. It is the lightest BYO option, it is the natural fit for local development, and it is the one host that can keep a workspace on disk between runs, so a sandbox can pick up where the last one left off instead of starting clean every time.

The full walkthrough, registering the host, running the operator, making it your default, and turning on persistent workspaces, is set up a Local Docker host.

How a host stays connected

However you run it, a host connects the same way, and the direction is the part worth understanding. The operator you run dials out to the platform over a managed messaging channel (Azure Web PubSub) and holds that connection open. The platform sends a command, launch this sandbox, tear that one down, over the channel the operator opened, and the operator answers back over the same channel. Nothing reaches into your network from outside, and you open no inbound ports.

This is what makes a bring-your-own host safe to run behind a firewall: it behaves like any other outbound client, the way a CI runner or a backup agent does. The deeper picture, the channel, the short-lived tokens, and how a host recovers if its connection drops, is network and connectivity.

A host reports its own state, and the list shows it. A new host reads Awaiting operator until its operator connects and claims it, then Registered while it is checking in, and it shows the connection as dropped if the operator goes away. Two things follow from this that are worth knowing. New work launches only on a registered host, so a profile pointed at a host whose operator is down gets a clear, early refusal instead of a confusing mid-run failure. And a host serves the runtime families it advertises, so the platform places a profile on a host equipped for the languages it needs rather than one that happens to be named.

Choosing where to run

The decision comes down to what the work needs, and the line is short.

• If you want agents to work with no infrastructure to operate, use managed. It is the default for a reason.
• If your organization requires agent runs to stay on compute it owns and governs, register a Kubernetes host and point the relevant profiles at it.
• If you want runs on your own machine, or you want a workspace that survives between runs for fast local development, register a Local Docker host and make it your default.

These are not mutually exclusive. A workspace can run most profiles on the managed host and point a few sensitive ones at a registered cluster, because the host is a per-profile choice. You are deciding, profile by profile, where that kind of work should live.

A capability for the teams that need it

Running your own host is an enterprise capability. Registering and managing hosts rides on hosts.manage, with hosts.read for the people who should see what hosts exist, and bringing your own host is gated by an entitlement on your plan, because it is the kind of control a security or platform team asks for rather than a default everyone needs. The managed option is available to every workspace from the first run; the bring-your-own options are there for the teams whose requirements call for them.

Why hosts work this way

The easy thing for a platform that runs containers on your behalf would be to run them only in its own cloud and never give you the choice. That is fine until the day a security review asks where the agent's code actually executed, or a data rule says certain work cannot leave your network, or you already have a cluster sitting there and no reason to pay for someone else's. A single managed location is the right default and the wrong mandate.

So the model separates two things that are usually welded together: the environment and the place it runs. The image, the runtime, the tools, and the policy are the platform's to supply and keep consistent. The compute is yours to choose. A bring-your-own host gets you the same managed environment on infrastructure you control, rather than a lesser version you have to assemble yourself. And the connection always runs outward from your host to the platform, never inward, so "run it inside our boundary" does not mean "open a hole in our boundary." The point is to make the location of the compute a setting, not a limitation, so the same agents can work where each piece of work belongs.

For a planner, none of this is in your way. The managed default means handing work to an agent never waits on infrastructure, and when a profile has been pointed at a particular host, your launch lands there without your having to think about it.

For an engineer, the host is how you get a real environment on your own machine. A Local Docker host runs sandboxes on your Docker Desktop and keeps a workspace between runs for a fast inner loop, built from the very same profile your teammates launch.

For a lead, the per-profile host choice is how you put the right work in the right place without policing it. Most work runs managed; the profiles that need to stay on your infrastructure point at it, and the decision lives in the profile rather than in everyone's habits.

For the person who owns the security boundary, this is the answer to "where does the agent's code run, and what did we have to expose to allow it." You can keep every run on compute you own, the operator reaches out rather than being reached into, you open no inbound ports, and registering a host is a gated, audited action. The location of agent execution becomes something you decide and can prove, not something you accept.