Sandbox profiles

A sandbox is disposable; a sandbox profile is not. The profile is the recipe the sandbox launches from: which image, which repositories, which AI runtime, which tools, how much CPU and memory, and the policy that governs what an agent can do inside. Configure a profile once, "Node 22, our API and front-end repos, Claude, two CPUs," and every sandbox of that kind comes up the same way, every time, in a click. The profile is what turns "the way we set up an Insights sandbox" from something one person does by hand, and gets slightly wrong, into something that comes up the same way every time.

This page is the operational how-to: where profiles live, what each part of the editor configures, and the parts worth understanding before you launch real work on one. For the concept, what a profile carries and how the platform composes an image from it, read sandboxed execution; this page is the editor.

Where profiles live

You manage profiles at Platform → Sandbox Profiles. Each profile has its own detail page, and the page is organized into tabs so a long configuration reads as a set of concerns rather than one endless form:

• Overview is the read-only rollup: what the profile launches with, the records using it, recent activity scoped to it, and a button to test it.
• General sets where the sandbox runs and who can use it: the provider, the host, the name and description, an optional environment binding, and the access list.
• Runtime picks the AI runtime and model, the MCP tools the agent can reach, and the skills the action launcher offers.
• Image composes what is in the container: the features layered into the image and the hooks that run while it builds and launches.
• Resources is the heaviest tab: the repositories to clone, the environment variables, the CPU and memory class, and the warm pool.
• Maintenance is the occasional-use tab: force an image rebuild, and manage workspace persistence.
• Commands holds the managed-command catalog and the enforcement mode that decides how strictly the agent's shell is governed.
• Agent Instructions carries a per-profile agent-instructions override, with its own version history.

Where the sandbox runs

The General tab decides where a sandbox from this profile actually runs. You first choose between a managed host that Disco Parrot runs and a host you bring yourself, and then the provider: Docker for a container on a Docker host (a managed one, or one you registered), Azure Container Apps for the platform-managed serverless option, and custom for a sandbox on a host you registered and operate yourself. The host target pairs with it: a profile can point at your workspace's default Local Docker host, so it follows whoever launches it, or at one specific host you name.

This is the field that puts a particular kind of work on the compute it should run on. A planning profile can sit on the managed option where nobody runs infrastructure; a profile that builds a heavy monorepo can point at a beefier host you registered. The how-to for registering hosts, and the trade-offs between Local Docker, Azure Container Apps, and your own Kubernetes cluster, is sandbox hosts and deployment options.

The repositories

The Resources tab is where you list the repositories a sandbox checks out, and each one carries more than a URL. A repository on a profile has a role, and the role is the part that matters:

• Primary is the repository the agent works in and writes to, the one a pull request comes back from.
• Context is a repository the agent reads for reference while it works, checked out alongside the primary.
• Reference is the same idea, read-only by intent, for code the agent should be able to consult but never change.

Each repository also takes a branch to start from, an optional clone depth (shallow for speed, full when history matters), and a mount path, which defaults to /workspace/<the repository's identifier> so a flow always knows where to find it. You can mark a checkout read-only when an agent should be able to read it but not touch it.

The credential that clones each repository is never stored on the profile. The profile names the repository by its identifier, and the clone-time token is minted at launch from your workspace's credential store, scoped to that one operation. A profile is a list of which repositories travel together, not a place secrets sit.

The image

The Image tab composes what is inside the container without making you hand-write a Dockerfile. You declare the features you want, named building blocks like Node 22, Postgres, or your cloud's CLI, drawn from the same devcontainer Features catalog the rest of the industry uses, and the platform layers them into the image at build time.

Alongside features, you can attach lifecycle hooks that run at the moment they belong to:

• Build hooks do the heavy work that should happen once per image, while the image is being built, not once per launch.
• Runtime hooks handle per-launch setup, like seeding a database or loading environment-specific config, each time a sandbox comes up.
• Prewarm hooks run while a warm-pool container is being prepared, so the cost of the slow work is paid before anyone ever attaches.

The result is an image you describe rather than one you maintain by hand, and anyone who can read the profile can see exactly what is in it. The deeper version of image composition, the runtime modes and how a managed base combines with your features, is in sandboxed execution.

How much it gets to use

A profile picks a resource class, which is the CPU-and-memory shape the sandbox launches with. There are three, sized to the kind of work:

• Planning, 1 CPU and 2Gi of memory, for planning, reading code, light edits, and short commands.
• Development, 2 CPU and 4Gi, the everyday class for dev servers, package installs, builds, and focused tests.
• Development-large, 4 CPU and 8Gi, for the heavy cases: large compiled monorepos, integration test suites, a full backend build.

When a class is close but not exact, you can override the CPU or memory limit on top of it, so a profile that needs the development class plus a little more headroom gets it without jumping a whole tier. The class is the dial you reach for first; the override is the fine adjustment.

Configuration and secrets

A profile carries environment variables for the non-secret configuration a sandbox needs: a feature flag, a region, a log level. These are plain values you set on the profile, and the editor checks them as you save: a value that looks like a credential is rejected, because secrets do not belong in an environment variable sitting on a profile.

Secrets reach a sandbox a different way, through the short-lived credential leases the platform mints at launch and the environment the profile is bound to, never as a literal typed into the profile. The line is deliberate, and it is the same line that runs through the whole platform: configuration is something you set and read, a secret is something the platform holds and leases. Approved actions covers how a credential is leased to a sandbox and never handed to the agent.

Managed commands and how strictly they are enforced

The Commands tab is where a profile can move from "the agent has a shell" to "the agent has a known set of commands." You define a catalog of managed commands, each one a named, fixed command with its own argument rules, working-directory limits, and the credentials it is allowed to use. Then you choose how strictly the catalog is enforced, and the three modes are a real spectrum:

• Advisory is the default and the lightest: the catalog is there as the preferred way to do things, with managed-command guidance surfaced to the agent, but the native shell stays open. Use it when you want the convenience of named commands without closing anything off.
• Redirect-known is stricter: when the agent reaches for a native command that matches a catalog entry, it is steered to the managed version instead. The catalog wins for the commands you have defined; everything else still runs.
• Strict-command is the tightest: managed execution is required for the command families you have defined, and the agent's native shell is closed. This is the mode for the environment where you want an agent to do exactly a defined set of things and nothing else.

The modes govern the agent's own command execution, not the platform's setup of the container, so strict mode locks down what the agent can run without breaking the image build or the tools the profile installed. A strict profile that also offers MCP tools needs those tools named explicitly rather than left wide open, or the run will not start, so the lockdown has no side door.

Warming, persistence, and identity

Three more controls round out a profile, each for a particular need:

The warm pool keeps a small inventory of ready containers for this profile so a person opening a chat attaches to one instead of waiting for a build. You turn it on, set a floor and a ceiling, and pick a strategy; the concept page covers the strategies, and the Sandboxes page shows the live pool.

Workspace persistence lets a profile keep its working volume between runs instead of starting clean each time, for the cases where rebuilding the workspace every launch is genuine waste. It is available on a Local Docker host you run yourself; sandboxes on the managed hosts and on Kubernetes stay disposable. Setting one up is covered in set up a Local Docker host.

Sandbox identity binds a workload identity to the profile, so a sandbox can authenticate to a cloud resource as itself rather than carrying a long-lived secret. Today that is an Azure user-assigned managed identity, and it sits on profiles that run on a host you registered.

Build a profile with AI chat

A profile has a lot of fields, and you do not have to fill them in cold. Each profile detail page carries an AI chat that builds and edits the profile with you: you describe the environment you want in plain language, and the agent makes the change by calling typed tools that mutate the profile one section at a time, each edit shown so you can see what it changed before you keep it. It is the same draft you would edit by hand, built by conversation, and it respects the same permissions: the agent can only change a profile you could change yourself. Because every change is a typed tool call against one section, it lands in the profile's activity the same as an edit you made in the form, so a profile built by conversation is exactly as auditable as one built by hand. The chat is a faster way to reach the same configuration, not a second, looser one.

Test it before you trust it

A profile is configuration, and configuration can be wrong in ways you only find when an agent is mid-run. The Test profile action, from the Overview tab, launches a one-off sandbox from the profile, runs a set of probes against it, and reports what works and what does not before any real work depends on it. The full test surface, what it probes and how to read the result, is test a sandbox profile.

Standardizing a profile, end to end

The Insights team has been launching agents against a setup that lived in one engineer's head: the right Node version, the API repo and the shared library it depends on, a Postgres for the integration tests. When that engineer was out, nobody else could quite reproduce it. Tom decides to make it a profile.

He creates one at Platform → Sandbox Profiles and names it Node 22 . Insights. On General he points it at the team's registered Docker host, the beefier one, because the integration suite is heavy. On Resources he adds two repositories: orcette/insights as Primary, the one agents write to and open pull requests from, and orcette/insights-shared as Reference, read-only, there to consult but never change. On Image he declares Node 22 and Postgres 16 as features rather than writing a Dockerfile, and picks the development-large class because the suite needs the headroom.

Then he sets the part that used to be a worry. On Commands he leaves enforcement on Advisory for now, the catalog present as the preferred path while the team gets used to it, with a note to himself to tighten it once the managed commands cover the real work. He populates the access list with the Insights engineers, so the profile that points at the heavier host is not something anyone can launch by accident.

Before he tells the team it exists, he hits Test profile from the Overview tab. The probes come back: the sidecar is healthy, both repos clone, Postgres answers, the runtime is reachable. Green. He shares the profile, and the setup that used to be one person's tribal knowledge is now a page the whole team can read, launch in a click, and test when they change it.

Who can manage and use a profile

Two concerns, two sets of permissions. Managing profiles, creating, editing, deleting, and testing them, is admin work held by sandbox-profiles.manage, with sandbox-profiles.read for everyone who should see the profiles that exist. Using a profile, launching a sandbox from it, is a lighter, separate scope, sandbox-profile.use.

A profile can also carry an access list. When it has none, anyone with sandbox-profile.use can launch from it. When you populate the list, only the users and roles on it can, and editing that list is its own scope, sandbox-profile.acl.manage, so a profile pointed at a sensitive host or a production-adjacent environment can be restricted to the people who should run it. Managers who can edit the profile bypass the list, since they own the configuration anyway.

Why profiles work this way

The alternative to a profile is the thing every team has lived through: a setup doc that drifts, an environment that works on one machine and not another, an agent that fails halfway through a run because a tool it needed was not installed. A profile makes the environment a declared, versioned, testable artifact instead of folklore. The image is described, not hand-rolled; the repositories and their roles are explicit; the resources are a class you pick; the agent's reach is a policy you set, from advisory all the way to a closed shell. The point is not configurability for its own sake. It is that "the environment our agents run in" stops being a thing only one person understands and becomes a page anyone on the team can read, test, and trust.

For a planner, a profile is what makes "run an agent against this kind of work" a one-click, repeatable thing rather than a setup you wait on an engineer for. The hard part was decided once; launching is the easy part.

For an engineer, the profile is the environment as code without the Dockerfile: declare the features, list the repos with their roles, pick the resource class, and every sandbox comes up the same. When something is missing, you test the profile and see it before an agent hits it mid-run.

For a lead, a profile is how a kind of work becomes standard without standing over anyone. You approve one environment, the team launches from it, and the next new hire is productive against it on day one instead of chasing a setup doc, with the access list keeping the sensitive profiles in the right hands.

For the person who has to govern what an agent can do, the profile is the control surface: the managed-command enforcement decides how much shell an agent gets, the access list decides who can launch, secrets never sit in the configuration, and the whole thing is readable and testable rather than assembled by hand in the dark. The agent's reach inside a sandbox is exactly what the profile grants, and the profile is a page you can audit.