Environments
Save a named, ordered set of repositories with its own secrets, prebuilt images, and settings overrides, then launch it from the new-session picker.
This page shows how to create an environment, what a session launched from one receives, and how environments interact with secrets, prebuilt images, and integrations.

What an environment is
An environment is a named, reusable set of repositories: the thing you reach for when the same multi-repository workspace comes up again and again (a frontend plus its API, a service plus its shared library). Environments are managed under Settings › Environments and appear at the top of the new-session picker.
An environment defines:
| Part | Details |
|---|---|
| Ordered repository list | Up to 10 repositories, each with a base branch. The base branch defaults to the repository's default branch. Two repositories with the same name cannot be in one environment, because each is checked out at /workspace/<repo-name>. |
| Primary repository | The first repository in the list. It supplies the sandbox and editor settings that the environment inherits unless you override them. |
| Environment secrets | Sessions receive global secrets, their owning team's secrets if team-owned, then the environment's secrets. |
| Prebuilt images | Optional. The whole environment (all clones, all setup scripts) is built ahead of time so sessions boot from the image. |
| Settings overrides | Per-environment overrides for the code editor, VNC desktop, and sandbox settings. |
How a session picks all of that up:
A name is limited to 200 characters and a description to 2,000. Names are unique within the owning team or workspace scope, not across the whole deployment; two teams can each have an environment named full-stack.
Ownership and access
Choose Team when creating an environment, or Workspace (no team) if workspace policy permits it. Ownership is fixed after creation. Team environments also appear on their team's Environments tab. See Teams for membership, repository grants, and the policy that can require a team for new resources.
| Action | Requirements |
|---|---|
| Read a workspace environment | environments.read |
| Read a team environment | environments.read plus either current owning-team membership or workspace Administrator/Owner authority |
| Use an environment | environments.use, access to the environment, and compatible session ownership; team sessions need grants for every included repository |
| Manage a workspace environment | environments.manage |
| Manage a team environment | environments.manage plus either owning-team lead or workspace Administrator/Owner authority |
A team-owned environment can launch only into a session owned by that same team, even for an administrator. A workspace-owned environment can also be used by an eligible team session; the team's session catalog can include those workspace environments when its repository grants cover the full set. An unbound bot cannot discover team environments.
Create an environment
Open the form
Go to Settings › Environments and click New environment, or use your team's Environments tab. You need environments.manage; creating for a team also requires team lead or workspace Administrator/Owner authority. Select the owning Team before choosing repositories. If workspace policy requires team ownership, Workspace (no team) is unavailable.
Name it and pick repositories
Fill in Name (for example full-stack) and an optional Description. Under Repositories, select the repositories to include. Every selected repository gets a row showing its base branch; the first row carries the primary badge. Use the up and down controls to reorder rows, Remove to drop one, and the branch picker on each row to change its base branch.
Decide on prebuilds
Turn on Prebuild images if you want an image with every repository cloned and every setup.sh already run. Saving with the toggle on starts a build immediately. See Prebuilt images.
Save and add secrets
Click Create environment. The page opens the new environment's Secrets tab, where you add environment secrets or import them from a member repository (see Secrets below).
Editing an environment later shows Configuration, Secrets, and Overrides tabs. Changes to secrets require environments.secrets.manage, settings changes require environments.settings.manage, and manual image builds require environments.images.manage. Each also requires environment management access, including environments.manage and the team lead/admin check for team environments. A custom role with only the feature-specific permission cannot make these changes, even on a workspace environment. Reading secret keys requires environments.secrets.manage plus environment read access; viewing overrides requires integrations.read plus environment read access.
The environment list shows each environment's name, its repositories, its description, the image build status, the prebuild toggle, a Rebuild image button, Edit, and Delete (which asks you to Confirm).
Use an environment from the picker
Environments appear at the top of the new-session picker, alongside single repositories. Pick one and the session clones every repository into one workspace, with each repository on the base branch the environment defines. There is no per-repository branch selector for an environment session; the branches come from the environment.
The picker also offers Multiple repositories, the ad-hoc counterpart. An ad-hoc set has the same workspace shape (each repository cloned side by side, one PR per repository possible) but it is not saved anywhere: it has no environment secrets, gets global secrets plus its owning team's secrets (if any) plus each selected repository's secrets instead, and never uses prebuilt images. The picker says so under the selection and links to Settings › Environments so you can save the set as an environment.
Secrets
A session launched from an environment receives global + the session's owning team (if any) + environment secrets, with later values winning. The repositories inside the environment do not contribute their repository secrets. This also applies when a team session uses a workspace-owned environment: the session's team supplies the team layer. Environments are curated, so a key added to a repository never silently lands in every environment containing it.
To reuse a repository secret in an environment, open the environment's Secrets tab and use Import from a repository:
- Pick a source repository. Only repositories that belong to the environment are offered; source-repository authorization and the destination team's grants are still checked.
- Tick the keys to copy.
- Click the Import button (its label shows how many keys are selected).
Values are copied on the control plane and never displayed. Imports are copies: if you later rotate the value on the repository, re-import it or update the environment secret directly. The alternative is to move the key to global scope. See Secrets for scopes and limits.
Saving secrets rebuilds the image
When prebuilds are enabled, changing an environment's secrets retires the existing ready image and triggers a rebuild. See Secrets and images for what a setup script must not write to disk.
Prebuilt images
With Prebuild images on, the environment's image is built from all repositories at their base branches, running each repository's .openinspect/setup.sh in position order. Sessions launched from the environment start from that image and skip setup.sh. Details, statuses, and timeouts are on Prebuilt images.
Two environment-specific rules:
- Editing the set retires the image. Every image records the ordered list of repositories and their base branches. Changing a repository, the order, or a base branch means the image no longer matches; sessions fall back to a normal boot until the rebuild finishes.
- Saving a prebuild-enabled environment triggers a build. So does changing its secrets, toggling prebuilds on, or clicking Rebuild image on the environment row.
Build secrets follow the environment's ownership: global + its owning team (if any) + environment secrets. Workspace environment builds do not receive the secrets of teams that later use them. Changing or deleting an owning team's secrets invalidates that team's environment images and schedules best-effort rebuilds when enabled.
Sessions snapshot the environment
A session copies the environment's repository set at creation time. Editing or deleting the environment afterwards never changes what an existing session works on. If the source environment is gone, the session's Repositories and Pull requests sidebar section shows an "Environment deleted" notice; the session itself keeps working.
An edit does affect new sessions and the prebuilt image, as described above.
Integrations can target environments
| Integration | How an environment is used |
|---|---|
| Slack | Routing rules under Settings › Integrations › Slack map a keyword to a repository or an environment. A channel can also be associated with an environment (up to 50 channels per environment). A rule whose environment was deleted shows "Deleted environment" and is ignored until it points at something that exists. |
| GitHub | A repository can carry a default environment. When the GitHub bot starts a session for that repository and the default environment contains it, the session launches the environment instead of the single repository. |
| Linear | Team and project mappings can point at an environment by its stable env_… id, optionally filtered by label. A mapping whose environment was deleted is skipped and resolution falls through to the next target. |
Sessions started by Slack, GitHub, and Linear run on the harness chosen in their integration settings (OpenCode by default). Slack users can also choose their own harness in the Slack app's Home tab.
An integration mapping does not bypass environment access or ownership checks. Team environments require a session owned by the same team; an unbound bot's workspace session cannot use one.
Per-environment overrides
The Overrides tab layers environment-specific settings above the primary repository's settings. Anything left unset inherits from the primary repository. Overrides apply to sessions launched from the environment and to its image builds.
| Override | Options |
|---|---|
| Code Editor | Inherit, Enabled, Disabled. Whether sessions get the browser-based editor. |
| VNC Desktop | Inherit, Enabled, Disabled. Whether sessions get a remote desktop. |
| Sandbox | The same fields as Settings › Sandbox (tunnel ports, terminal, child-session limits, CPU and memory, timeouts, build timeout, session cost limit). Inherited values are shown as the current settings; saving pins only the fields you change. |
Troubleshooting
Next steps
Repository lifecycle scripts
Add .openinspect/setup.sh and .openinspect/start.sh to a repository so sessions install dependencies and start services before the agent begins work.
Prebuilt images
Enable prebuilt images for a repository or an environment so sessions start from an artifact that already has the code and dependencies in place.