Skip to content

feat(core): add opt-in OS-level shell sandbox - #63599

Open
alexm-redhat wants to merge 1 commit into
anomalyco:devfrom
alexm-redhat:sandbox-shell-commands
Open

alexm-redhat wants to merge 1 commit into
anomalyco:devfrom
alexm-redhat:sandbox-shell-commands

Conversation

@alexm-redhat

@alexm-redhat alexm-redhat commented Nov 12, 2026 •

Copy link
Copy Markdown

Issue for this PR

Addresses the sandboxed-execution part of #48411.

Type of change

  • New feature

What does this PR do?

Adds an opt-in OS-level sandbox for the shell tool. When enabled, shell commands are wrapped in bubblewrap on Linux or sandbox-exec on macOS, with a read-only or workspace-write filesystem, network denied by default, and fail-closed behavior when the backend is missing.

{
  "sandbox": { "enabled": true, "mode": "workspace-write", "network": "deny" },
}

The sandbox applies only to shell commands. Leaving it requires the separate shell_unsandboxed permission (ask by default), so approving a command never approves escaping the sandbox. Policy is pinned per workspace on first use; changing sandbox settings needs a restart. Existing config files are bound read-only; absent or symlinked config paths stay ordinary workspace content.

This is a core feature and CONTRIBUTING.md asks for design approval before implementation. The branch is prepared for that review; happy to adjust the approach.

How did you verify your code works?

  • cd packages/core && bun run typecheck
  • cd packages/core && bun test test/sandbox.test.ts test/shell-daemon.test.ts test/shell-sandbox-spawner.test.ts test/tool-shell.test.ts test/config/normalization.test.ts test/agent.test.ts
  • cd packages/schema && bun test
  • cd packages/protocol && bun run check:generated
  • Full packages/core suite: 7,132 pass, 350 skip, 23 pre-existing failures, zero new (bun run test).
  • Live bubblewrap tests on Linux confirm writes outside the workspace are denied. The macOS profile is string-tested on this Linux host, not executed.

Screenshots / recordings

Not a UI change.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Amalgamator was used for AI assistance (https://github.com/amalgamator-ai/amalgamator)


Added by the opencode bot (AI-generated).

Related: #48411, #2242

Public API: adds the sandbox config key, the shell_unsandboxed permission and an optional sandbox input on the shell tool (backwards compatible, off by default)

Wrap shell tool commands with bubblewrap on Linux and sandbox-exec on macOS.
The sandbox supports read-only and workspace-write modes, denies the network
by default, and fails closed when the backend is unavailable.

A `sandbox: false` call requires the separate `shell_unsandboxed` permission,
which defaults to ask, so approving a command never approves leaving the
sandbox. Sandbox settings are pinned per workspace on first use.

Amalgamator was used for AI assistance (https://github.com/amalgamator-ai/amalgamator)

Signed-off-by: Alexander Matveev <amatveev@redhat.com>

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bubblewrap wrapper does what it says on Linux, but the sandbox still has an escape that survives a restart. I installed bubblewrap and ran Sandbox.wrap in workspace-write mode: writes outside the workspace and outbound TCP were blocked, and an existing opencode.json stayed read-only. I couldn't run the macOS profile or OpenCode end-to-end. As the description says, this is a core feature that CONTRIBUTING.md wants design-approved first, so the overall approach needs a maintainer's decision.

Public API (all additions, backwards compatible; the sandbox is off unless enabled):

  • a new sandbox config key with enabled, mode, network, writable_roots and readable_roots, plus the generated OpenAPI spec and client types;
  • a new shell_unsandboxed permission, set to ask in the default agent ruleset;
  • a new optional sandbox boolean input on the shell tool.

Concerns:

  • A confined command can plant an escape for the next start (blocking). Only config files that already exist are bound read-only. In a fresh workspace, a sandboxed command created .opencode/plugins/evil.ts and an opencode.json with {"sandbox":{"network":"allow","writable_roots":["/"]}}; .claude/ and .agents/ are config sources too and aren't protected. After a restart the plugin runs inside OpenCode with no sandbox, and the policy is widened. Pinning only covers the current process. See the inline comments.
  • Repo config can loosen the user's sandbox. A project opencode.json can turn network on when the user's config leaves it unset (the default), and can add writable roots. A cloned repository shouldn't be able to widen the sandbox the user enabled.
  • It confines more than the shell tool. The wrap happens in Shell.Service, so the user's own ! shell commands and plugin shells run confined too, with no shell_unsandboxed way out. If that's intended, the description and docs should say so; otherwise the decision belongs in the tool path.
  • Policy is kept in a module-level Map. It's process-wide state outside the Effect services, keyed by directory and never cleared (it needs a resetPolicies test hook). It would fit better as part of a Location-scoped service.
  • The live network test is brittle. It counts interfaces in /proc/net/dev, and on my kernel the new namespace had 9 tunnel devices (tunl0, gre0, …), so the test failed while the network was in fact blocked. Testing an actual connection attempt would be more reliable.
  • The base is behind dev, which has recent changes to packages/core/src/shell.ts (#63409, #62978), so this may need a rebase.

Related: #48411, #2242

* Workspace paths a sandboxed command can never write, even in `workspace-write`: the files that configure the
* sandbox. Otherwise a confined command could write `{"sandbox":{"enabled":false}}` and run unconfined next time.
*/
export const PROTECTED = ["opencode.json", "opencode.jsonc", ".opencode"] as const

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list leaves out other config sources: .claude and .agents are discovered as config directories too (config/discovery.ts). Also, it only protects paths that already exist (see protectedPaths below). In a workspace without them, a confined command could create .opencode/plugins/evil.ts and opencode.json with {"sandbox":{"network":"allow","writable_roots":["/"]}}; I reproduced this with bubblewrap. On the next start the plugin runs inside OpenCode, outside any sandbox. Absent config paths need protecting as well (e.g. mount a read-only empty placeholder, or deny creating them), and probably .git/hooks too, as other workspace-write sandboxes do.

// already exist are bound: bubblewrap has to create a mount point for a missing target, which would leave an
// empty file in the workspace behind, and it refuses to mount on a symlink destination at all. An absent or
// symlinked config path is workspace content a command may create or replace, like any other file.
const protectedPaths =

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Skipping absent and symlinked paths is where the escape above gets in. Pinning stops a planted config from affecting this process, but not the next one, so here 'absent' has to mean 'cannot be created', not 'ordinary workspace content'.

const pick = <K extends keyof ConfigSandbox.Info>(key: K) =>
layers.findLast((layer) => layer[key] !== undefined)?.[key]
const roots = <K extends "writable_roots" | "readable_roots">(key: K) => {
const all = layers.flatMap((layer) => layer[key] ?? [])

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Roots add up across layers, and network: "allow" from a project layer wins whenever no layer says deny. The schema default is deny, but the user usually leaves it unset. So a cloned repository's opencode.json can widen a sandbox the user turned on, both network and writable roots. Should widening settings only be accepted from global, system or managed config?

// Pinned per workspace on first use, so config written by a confined command cannot change this process's
// policy. Fails closed: an enabled sandbox that cannot confine the command stops it from running at all.
const entries = yield* config.entries()
const policy = Sandbox.policy(entries, location.directory)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sandbox is applied in Shell.Service, which SessionShell.start (the user's own ! commands) and plugins also use. Those get confined with no way to opt out, because only the tool can pass unsandboxed. The description says the sandbox applies only to the shell tool. Either the caller should decide (e.g. the tool asks for confinement explicitly), or the docs need to say user commands are confined too. Also, the per-workspace pin is a module-level Map that is never cleared; it would fit better as part of a Location-scoped service than as process-global state.

}
})

test("denies the network by default and shares it only when allowed", () =>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This fails on hosts whose new network namespace has tunnel devices (tunl0, gre0, sit0…): I got 9 instead of 0 here, although outbound connections did fail with 'Network is unreachable'. Checking an actual connection attempt (e.g. to a local listener started outside the sandbox) would test the actual behaviour and not depend on the kernel's modules.

@alexm-redhat

alexm-redhat commented Nov 12, 2026 •

Copy link
Copy Markdown
Author

@rekram1-node would be good to get a sanity check. If the change makes sense and whether it is interesting for the project. Happy to adjust whether needed.

@alexm-redhat

Copy link
Copy Markdown
Author

@rekram1-node a quick feedback would be helpful.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant