OpenShell host

bobby-browser integrates with NVIDIA OpenShell as a host runtime: the sandboxed agent stays inside OpenShell; bobby and the Firefox companion stay on the host. OpenShell owns filesystem, process, and egress policy. bobby owns browser automation, capabilities, and evidence.

Topology

Layer	Role
OpenShell sandbox	Agent process, skill, MCP client; deny-by-default egress
OpenShell policy proxy	Only allowlisted MCP Streamable HTTP to host bobby
Host `bobby serve`	MCP at `POST /v1/mcp` + Firefox companion
Host operator	Mint/revoke one principal per sandbox (`authority:admin`)

One OpenShell sandbox ↔ one bobby principal. Default capability floor is the narrow openshell preset (no authority:admin, no JS eval / vision / jobs / fingerprint / humanize). Use --capabilities-preset agent only when needed.

Isolation constraints

Shared Firefox companion: cookies, logins, and the durable context graph

are profile-scoped, not principal-scoped. Two sandboxes on the same host companion share site state. For stronger isolation use a dedicated companion profile per sandbox, or managed Chromium disposable workers (no persistent logins). bobby doctor warns (openshell-companion) when ≥2 local sandboxes share one enrolled companion.

Cleartext MCP: default mcp.json uses http:// to the host gateway.

Firewall that path; do not bind bobby to untrusted networks. Doctor reports openshell-cleartext when the MCP URL or server.host is non-loopback HTTP.

Policy replace: openshell policy set replaces the entire sandbox policy.

Prefer merging openshell/policy-network.yaml into an existing policy when you already customize filesystem/process sections.

Install the pack

bobby install --host openshell --yes
# or:
bobby openshell install
bobby init --emit openshell

Writes project openshell/:

policy.yaml — full OpenShell sample (protocol: mcp allowlist; denies

evaluate_javascript / job_* at the proxy as defense in depth)

policy-network.yaml — merge-only network_policies fragment (do not

policy set this file alone)

mcp.json — streamable-HTTP client config (Bearer ${AUTOMATION_RUNTIME_TOKEN})
skills/bobby-browser/SKILL.md — agent skill copy
README.md — operator steps

Default gateway host is host.docker.internal:7777 (Docker Desktop). Override:

bobby openshell install --mcp-host host.containers.internal --mcp-port 7777 \
  --agent-binary /usr/local/bin/claude

Host prerequisites

bobby init --preset unrestricted (needed to mint principals)
Firefox companion paired (bobby install --companion, then Pair) — or accept

shared-profile risk / use Chromium disposable instead

bobby serve reachable from the sandbox via the host gateway address
Keep bind scoped — loopback plus the gateway interface OpenShell can dial

Per-sandbox provision

bobby openshell provision --sandbox demo-1
# revokes any prior principal for demo-1, mints a fresh one (unique idempotency key)
# writes ~/.config/bobby-browser/openshell/demo-1.env (0600)
# inject AUTOMATION_RUNTIME_TOKEN into the OpenShell sandbox credentials
openshell policy set demo-1 --policy openshell/policy.yaml --wait
# or merge openshell/policy-network.yaml into an existing policy, then policy set

Prefer BOBBY_MCP_TOOLSET=explore (or act) inside the sandbox so tools/list stays under OpenShell’s MCP body budget.

Wider capabilities when required:

bobby openshell provision --sandbox demo-1 --capabilities-preset agent

rotate is the same operation as provision: it revokes the prior principal and mints a fresh one. list and status --sandbox <id> report the locally recorded sandboxes from non-secret .status.json sidecars — neither prints a token.

When the sandbox ends:

bobby openshell revoke --sandbox demo-1

The secrets root is <os-config-dir>/bobby-browser/openshell/ — ~/.config/… on Linux, ~/Library/Application Support/… on macOS. BOBBY_OPENSHELL_SECRETS_DIR overrides it for tests and alternate secret roots; it is process-global, so set it for the whole command rather than per-sandbox.

Shared `/v1` client behavior

OpenShell operator commands and jobs tooling share the same blocking /v1 HTTP client (v1_client) in the host runtime. This keeps bearer and interface headers, timeouts, retries, and request behavior consistent across principal lifecycle operations and /v1/jobs calls under the same OpenShell session.

Re-running provision (or rotate) for the same sandbox id rotates: prior principal is revoked first, then a new principal is minted.

bobby openshell list
bobby openshell status --sandbox demo-1
bobby openshell rotate --sandbox demo-1

Doctor

If openshell/ is present in the working directory, bobby doctor reports openshell-pack plus openshell-admin, openshell-companion, openshell-mcp-url, openshell-cleartext, and openshell-sandboxes (and warns when an older pack lacks hardened deny_rules or policy-network.yaml).

Non-goals

Running Chromium/Firefox *inside* the OpenShell sandbox
A bobby-side relay control plane (use OpenShell’s supervisor proxy)
Minting tokens from inside the sandbox