feat: make host and agent execution environments explicit #381

New issue

Open

opened 2026-07-18 00:17:19 +02:00 by dries · 0 comments

dries commented

2026-07-18 00:17:19 +02:00

Owner

Parent

#375

What to build

Define and surface the execution semantics when OpenCode runs in a managed container while the in-app terminal, git/forge operations, and workflow command nodes remain host-native. Users must be able to tell which environment will execute an action and must not be led to assume identical tools, credentials, network, or PATH.

For the first version, keep host terminals and workflow command nodes host-native unless a concrete workflow requires container execution. Do not add a container PTY/exec subsystem speculatively.

Acceptance criteria

Product and architecture documentation define which operations execute on the host and which execute in the managed OpenCode runtime.
Session/runtime UI identifies container-backed agent execution without branching on a platform identity.
Terminal and workflow command affordances clearly indicate that they execute on the host when the session agent is container-backed.
Git/worktree/forge ownership remains host-side and observes container edits through shared files.
Common divergence cases have actionable guidance: missing tools, different PATH, package caches, credentials, network services, and UID/GID ownership.
Runtime diagnostics report enough non-secret environment metadata to explain divergence.
No container shell/PTY feature is added unless required by an acceptance test that host-native execution cannot satisfy.
Frontend and integration tests cover capability-driven runtime labels and the host-execution messaging.

Blocked by

#378

## Parent #375 ## What to build Define and surface the execution semantics when OpenCode runs in a managed container while the in-app terminal, git/forge operations, and workflow command nodes remain host-native. Users must be able to tell which environment will execute an action and must not be led to assume identical tools, credentials, network, or PATH. For the first version, keep host terminals and workflow command nodes host-native unless a concrete workflow requires container execution. Do not add a container PTY/exec subsystem speculatively. ## Acceptance criteria - [ ] Product and architecture documentation define which operations execute on the host and which execute in the managed OpenCode runtime. - [ ] Session/runtime UI identifies container-backed agent execution without branching on a platform identity. - [ ] Terminal and workflow command affordances clearly indicate that they execute on the host when the session agent is container-backed. - [ ] Git/worktree/forge ownership remains host-side and observes container edits through shared files. - [ ] Common divergence cases have actionable guidance: missing tools, different PATH, package caches, credentials, network services, and UID/GID ownership. - [ ] Runtime diagnostics report enough non-secret environment metadata to explain divergence. - [ ] No container shell/PTY feature is added unless required by an acceptance test that host-native execution cannot satisfy. - [ ] Frontend and integration tests cover capability-driven runtime labels and the host-execution messaging. ## Blocked by - #378