Environments

When an agent does real work, it is always working against something: a staging database, a production cluster, a preview stack. An environment is how Disco Parrot names that target and sets the rules for it. Each environment carries a change policy, a per-axis decision about what an agent may apply directly and what it may only ever propose for a person to review. A staging environment can let an agent move quickly. A production environment can hold the line on a schema migration or an infrastructure change, so those never go live without a human in the loop.

This page is the operational how-to: the change policy and its axes, how a propose-only line is actually enforced, the health an environment reports, and how you bind one to a sandbox profile so the policy reaches the work. For the concept of why an agent's reach is bounded this way, read approved actions; this page is the environment editor and the health surface around it.

Every workspace starts with a default environment already in place, carrying safe defaults, so an agent is governed from the first run whether or not anyone has set up an environment by hand. The default is always there and cannot be deleted, but its policy, variables, and patterns are yours to edit, so you can tighten or loosen the baseline that every unbound run inherits. You create more environments when a target needs different lines than that baseline.

You manage environments at Platform → Environments. Each one has its own detail page, organized into tabs: Policy for the change policy, Settings for its identity and variables, Probes and Patterns for the readiness checks and artifact patterns, and Events for its health. The rest of this page follows those tabs.

The change policy

The heart of an environment is its change policy: five axes, each set to one of two modes. Apply-allowed means an agent may make that class of change directly. Propose-only means the agent prepares the change as reviewable source and stops short of pushing it live, and the change comes back to a person.

The defaults are chosen so the common case is fast and the dangerous cases are held:

So out of the box an agent writes code freely and opens a pull request, while a migration, an infrastructure change, a pipeline edit, or a secret change comes back as a proposal. You set this per environment: a staging target and a production target hold different lines, and an agent working against each one is governed by the policy that target carries.

How a propose-only line is enforced

Propose-only is not a suggestion the agent is trusted to honor. The platform watches what a run actually changes, and when a change lands on a propose-only axis, it stops the run rather than letting it carry on as though the change were already live.

The mechanism is artifact detection. As a run works, the platform notices the kind of change it is making and which axis it lands on:

• a migration file touches the schema axis.
• an infrastructure-as-code change touches the infrastructure axis.
• a credential or role change touches secrets and identity.

When that axis is propose-only on the bound environment, the platform raises a blocking health event and parks the run at its next runtime-dependent step. The agent can still write the change as reviewable source, the migration script, the IaC diff, but it cannot reach the apply-class step that would push it to the live target.

There is a second trigger. When an infrastructure or database tool fails because a credential is missing, a capability gap, the platform raises the same kind of blocking event, so an agent that cannot authenticate to a cluster or a database stops with a clear blocker instead of flailing. The platform recognizes this for the common cloud, Kubernetes, Terraform, and database clients, where a missing-credential failure is an unmistakable signal that the target is not set up for the run rather than a bug in the work.

The change comes back the way every reviewed change does: as source a person reads and ships through the normal pull-request path. The propose-only line does not slow down the safe work, the code an agent writes still flows; it catches the specific changes you decided an agent should never apply alone, and routes them to review.

What counts as a change

A propose-only line is only as good as the platform's ability to recognize when a run has crossed it, so it is worth knowing how a change gets matched to an axis. The platform starts from conventions it already knows: migration and Prisma folders read as schema, Terraform and Kubernetes manifests as infrastructure, workflow files as pipeline and environment config, secret manifests as secrets and identity. When a run touches a file that matches, the platform knows which line the change is testing, and the policy on that line decides what happens next.

On the schema axis you can go further. An environment can carry its own artifact patterns, so detection matches the way your repository is actually laid out rather than only the built-in shapes, for the team whose migrations live somewhere the conventions would miss. The guarantee a propose-only line makes is only as strong as what the platform can recognize, so on the axis teams most often arrange their own way, the recognition is yours to tune.

The health an environment reports

Because those blocking events live on the environment, an environment has a health you can read at a glance. The status is one of four, derived from the events currently open against it:

• Healthy has nothing open against it. Work proceeds.
• Degraded has an open warning but nothing blocking. A signal worth seeing, not a stop.
• Blocked has at least one open blocking event. Runtime-dependent work against this environment parks until the event is cleared.
• Unknown means nothing has run against the environment yet. It is the resting state before the first run.

Each blocking or warning event is a record in its own right, and the events list on the environment is where you read and clear them. An event carries:

• its severity: blocking, warning, or info.
• a reason that names what raised it: an infrastructure, schema, pipeline-or-config, or secret-and-identity change required, or a capability gap.
• a short summary and the artifacts behind it: the files, the pull request, or the command that failed.
• the plans and initiatives it affects.

You clear an event two ways. Resolve it once the change has shipped through review, or dismiss it when it does not apply. Both are held by admins and owners, and both are recorded with who did it and why.

Where a blocker shows up on the work

A blocking event does not only live on the environment page where an admin would look. It surfaces on the work it affects. When an event blocks a plan or an initiative, a banner appears above the tab bar on that plan or initiative's own page, naming the environment, the reason, and the artifacts, with a Resolve control for whoever can manage that plan or initiative. Everyone else sees the blocker and understands why their work parked, but cannot clear it.

That is what closes the loop for the person doing the work. An engineer on the CSV Export plan does not have to know an environment exists to understand why their run parked: the blocker is on their plan, in plain language, telling them a schema migration on a propose-only environment is waiting for review. The environment carries the policy; the work carries the consequence, where the person who hit it will see it.

What else an environment carries

Beyond the policy, an environment holds the configuration that belongs to a target rather than to a profile.

Variables. An environment carries its own environment variables, and because some of what a target needs is sensitive, an environment variable can reference a secret rather than holding a literal. When a profile is bound to an environment, those variables join the run, so the configuration that is specific to "production" lives with production rather than being copied onto every profile that points at it. When a profile and its environment both set the same variable, the profile's value wins, so a profile can override a target-level default for its own runs.

Capabilities. An environment can also declare capability bindings, the named credentials a target governs, each with a delivery mode that controls how the credential reaches the sandbox without ever being handed to the agent as a plain value, from a temporary file or standard input to a Git credential helper or an outbound proxy. Every delivery mode but one points at a stored secret rather than a literal, and the editor will not let you save a binding that names a credential without one, so a capability is always backed by a real secret. This is the environment-level companion to the per-profile capabilities, a governed set of bindings declared once for the target.

Readiness checks. An environment can record the readiness checks that describe what "ready" means for it, on its own Probes tab. Each check is a label plus a command or a URL, the concrete test that stands for "this target is up." They live in the environment's definition alongside the policy, so the readiness contract for a target is written down in one place rather than living in one engineer's head, there for anyone setting the target up or reasoning about why a run against it behaved the way it did.

Binding an environment to a profile

A policy only matters if it reaches the work, and the bridge is the sandbox profile. A profile carries an optional environment binding on its General tab; set it, and every sandbox that launches from the profile runs against that environment, inheriting its change policy, its variables, and its health. Leave it unset and the run uses the workspace default.

This is why a staging profile and a production profile are different things, not just two names. Point the staging profile at a permissive environment and the production profile at a strict one, and the same agent, doing the same kind of work, is governed differently depending on which profile launched it. Choosing the profile is choosing the lines the run will hold.

Holding the line on production, end to end

The Insights team runs agents against two targets. Staging is where work moves fast; production is where a mistake costs a war room. Marcus, who owns the service, sets up a Production environment and leaves the defaults where they are: code apply-allowed, but schema, infrastructure, pipeline, and secrets all propose-only. He binds it to the production sandbox profile, the one only a few engineers can launch.

Weeks later, an agent working the CSV Export plan needs an index on a large table to make the export fast, so it writes a database migration. Against staging, that would just happen. Against production, the platform sees a migration land on a propose-only axis, raises a blocking health event with the reason "schema migration required," and parks the run at its next runtime-dependent step. The agent has written the migration as a reviewable script; it has not, and cannot, apply it to the production database.

Tom, working the plan, does not have to go looking. The blocker is on the CSV Export plan page, above the tabs, naming the environment and the migration file. He reviews the migration, ships it through the normal pull-request path the way a production schema change is supposed to go, and then resolves the event from the plan. The run picks back up. Nothing about the policy slowed the agent's actual code; it caught exactly the one change that should never have gone live on its own, and made a person the one who shipped it.

Who can see and manage environments

Reading environments is open within the workspace, so anyone can see what targets exist and what lines they hold. Creating, editing, and deleting an environment, and changing its policy, is reserved for your workspace admins and owners, because those changes move where the lines sit. Clearing a health event from the environment page, whether you resolve it or dismiss it, is held to those same admins and owners, so the people who can wave a blocking change through are the people accountable for the target.

There is one deliberate widening. The Resolve control on the plan or initiative banner is open to whoever can manage that plan or initiative, not only to a tenant admin, so the person who actually owns the work and shipped the reviewed change can clear the blocker from where they are standing. The arrangement keeps everyone able to read the rules, keeps the policy itself in admin hands, and still lets the right person unblock their own work.

Why environments work this way

The instinct when you give an agent real capability is to reach for a single global switch: agents may do this, agents may not do that, everywhere. That switch is always wrong somewhere. The reach that is fine against a scratch database is reckless against the production cluster, and a policy that has to be safe enough for production ends up strangling the work that should move fast. Environments exist to make the policy local to the target, which is the only place it is ever actually true.

Everything else follows from that. The policy is five axes rather than one toggle, because "what an agent may change" is not one decision: writing code, migrating a schema, provisioning infrastructure, and rotating a secret carry wildly different blast radii, and the defaults reflect it. Enforcement lives in the platform, not in the agent's good behavior, because a control an agent could ignore is not a control at all. A blocked change still gets written as reviewable source, because the goal is review, not refusal: the work moves forward, a person ships the risky part. The block surfaces on the affected work, not only on an admin page, so the person who hit it understands it. And the whole thing is auditable, because for the people who answer for a production target, "the agent was not allowed to" has to be something you can prove after the fact, not something you hope was true.

For a planner, an environment is why "let an agent work on this" does not mean "let an agent change anything." The risky classes of change come back as proposals you can see, so handing work to an agent against a real target is a decision you can make without holding your breath.

For an engineer, it is a policy that stays out of your way until it matters. Your code flows; the migration or the infrastructure change parks with a clear blocker on the plan, and you ship that part through review the way you would have anyway. You are never guessing why a run stopped.

For a lead, environments are how "production is different" becomes a setting instead of a standing worry. You set the lines once per target, bind the strict environment to the profile only a few people can launch, and the same agents move fast on staging and carefully on production without anyone policing it by hand.

For the person who owns the production target, this is least privilege made operational. The reach of every run is bounded by the environment it is bound to, the propose-only axes route the dangerous changes to a human, the blocks are enforced by the platform rather than trusted to the agent, and every event, every resolve, every dismiss is recorded. You can answer "could the agent have changed the schema" with the policy, and "did it" with the trail.