Environments

Agent Environments are reusable execution targets for Agent Ops threads. An environment defines the runner, repo, sandbox timeout, GCP vars, capability restrictions, and secrets that a thread runs with; pick one when starting a new thread. New environment creates. The environments surface is /ai/agents/environments.

The environment decides what the agent can see and touch, so it is a scope decision, not a preference. Wrong environment is the most common beginner mistake; when none looks right, stop and ask your admin or the PRESHai team.

• Each card names the runner, model, repository linkage, and Active state. Detail carries the full scope: runner, repo, timeout, GCP vars, capability restrictions, secrets.
• A linked repo gives the thread code context; unlinked cards run without one.
• Legacy cards exist for continuity; prefer the current Default unless your admin says otherwise.

Environment scope vs. agent scope

Two bundles meet at session start. Do not mix them up:

• Environment owns where it runs: runner, repository linkage, sandbox timeout, GCP vars, capability restrictions, secrets and policy. One session runs in one sandbox under one environment.
• Agent owns who runs: prompt, model, tools, skills, memory. Pick the agent the task needs, not the busiest one.
• The session is the overlap. Installs and grants resolve at session start (resolveAgentPluginRuntime) into what the run may actually call — visible in the session plugins panel, proven in the transcript. Where install and grant disagree, deny wins. See Plugins in session.
• The repository comes from the environment, not the agent. A session missing repo context is an environment problem, never an agent problem.

Environment owns where it runs — runner, repository linkage, sandbox timeout, capability restrictions, secrets. Agent owns who runs — prompt, model, tools, skills, memory. The session is where the two resolve into what the run may actually call.

Some environment fields are stored but not yet consumed at runtime. The list above names the scopes sessions actually run with; for anything else on the environment record, confirm in a test session before promising it to users — stored is not live.

The detail record carries the full scope behind a card: repository owner, name, and default branch plus working directory, runtime, and timeout. Tabs separate environment, workspace and sandbox, variables, access, and danger zone — the card is the summary, detail is the scope.

• Repository linkage decides code context: owner, name, and default branch are set here, not on the agent.
• Sandbox runtime and timeout bound the run; overly short timeouts stall multi-step work.

The Access tab is shares, not tool grants: it decides who can use this environment for Agent Ops sessions. Editors can also manage variables and shares; repo-backed environments show each shared user’s GitHub connection status for attribution — share does not grant GitHub access. Here there are no additional shares yet; anyone with org-wide Agent Environments permissions can still reach it via Object Manager roles.

• This panel never lists tool scope. When the task needs a specific system, confirm it in a test session — stored fields elsewhere on the record are not proof the run can reach it.
• No locked tool-grant capture exists yet; the live scope is proven in the session plugins panel and the transcript, not here.

Picking an environment

The environments list is the picker inventory: one card per execution target with runner, repository linkage, and Active state. New environment creates the next one — picking happens later, in the session composer.

• Prefer the current Default unless the task needs the linked repo on PRESHos (develop).
• Unlinked cards run without code context; legacy cards exist for continuity.

The composer environment picker is where the scope decision lands: one environment per session, chosen before the run starts. The dropdown lists the same targets as the environments list — Default, Default (legacy), PRESHos (develop).

• Match the environment to the task systems and risk before writing the task sentence.
• When none looks right, stop and ask the tenant admin; the composer never fixes a missing environment.

• Match the task systems and risk: the environment whose repo, tool grants, and secrets cover exactly this goal. Over-broad environments turn routine work into approval noise; under-scoped ones stall the run.
• Match the timeout to the work: long builds and multi-step runs need a longer leash; routine reads do not. Timeout is an environment setting, not something the session negotiates mid-run.
• Check the tool-grant list before starting, not after stalling. If the system the task needs is not granted here, no prompt wording fixes it — pick another environment or ask the tenant admin.
• No environments visible means stopping and asking the tenant admin. Do not improvise around a missing environment.

Verify before users arrive: the probe sequence

Run these as test sessions, in order. Each must pass before the next: happy-path read, boundary probe (out-of-scope unreachable, confirmed by attempt not assumption), draft quality, gate check (what, on-what, why intact), denial path (denied work degrades gracefully), wrong-org check (org_id correct). A failed probe loops back to the build; a full pass moves to capabilities. Full sequence and the environment spec template: FDE environment.

Environments lead to the first governed session on the tenant hostname. If no environment is visible, stop and ask the PRESHai team; do not improvise. Day-to-day use: Starting a session.

What next

• Agents: the agent inventory picked next to the environment.
• Starting a session: where the environment picker scopes a session.
• Agent config: the configured agent that runs inside the environment.
• Plugins in session: how grants and environment scope meet at runtime.
• Sandbox: the isolated space the environment starts.