horus-3d/docs/permissions-sandboxing.md

# Permissions, Sandboxing, and Workspaces (Studio -> Gateway -> PI)

This document exists to onboard coding agents quickly when debugging:
- Why an agent can or cannot read/write files
- Why command execution requires approvals (or not)
- Why a sandboxed run behaves differently from a non-sandboxed run
- How “create agent” choices in **Claw3D** flow into the **OpenClaw Gateway** (often running on an EC2 host) where enforcement actually happens

Scope:
- Studio one-step agent creation and post-create authority updates, including exact gateway calls.
- The upstream OpenClaw implementation that persists and enforces those settings at runtime.

Non-scope:
- Full PI internal reasoning/toolchain. Studio does not implement PI logic; it configures and displays the Gateway session.
- Any private EC2 runbook or SSH/hostnames. Keep this doc repo-safe.

## Mental Model (First Principles)

Studio is a UI + proxy. It does two things related to “permissions”:
1. Writes **configuration** into the Gateway (per-agent overrides in `openclaw.json`).
2. Writes **policy** into the Gateway (per-agent exec approvals in `exec-approvals.json`).

The Gateway (OpenClaw) is the enforcement point:
- It decides whether a session is sandboxed.
- It decides which workspace is mounted into the sandbox.
- It constructs the PI toolset (read/write/edit/apply_patch/exec/etc) based on config + sandbox context.
- It asks for exec approvals when policy requires it and broadcasts approval events.

## Glossary

- **Gateway**: OpenClaw Gateway WebSocket server (upstream project).
- **Studio**: this repo. Next.js UI plus a Node WS proxy.
- **Agent**: an OpenClaw agent entry stored in gateway config (`agents.list[]`).
- **Session key**: OpenClaw session identifier. Studio uses `agent:<agentId>:<mainKey>` for the agent’s “main” session.
- **Agent workspace**: a directory on the Gateway host filesystem configured per-agent (where bootstrap files and edits live).
- **Sandbox workspace**: a separate directory used when a session is sandboxed and `workspaceAccess` is not `rw`.
- **Sandbox mode** (`sandbox.mode`): when to sandbox (`off`, `non-main`, `all`).
- **Workspace access** (`sandbox.workspaceAccess`): how the sandbox relates to the agent workspace (`none`, `ro`, `rw`).
- **Tool policy** (`tools.profile`, `tools.alsoAllow`, `tools.deny`): allow/deny gating for PI tools (OpenClaw resolves effective policy).
- **Exec approvals policy**: per-agent `{ security, ask, allowlist }` stored in exec approvals file; drives “Allow once / Always allow / Deny” UX.

## Studio: Where “Permissions” Are Chosen

Agent creation is intentionally lightweight:
- `src/features/agents/components/AgentCreateModal.tsx` captures `name` and optional avatar shuffle seed.
- `src/features/agents/operations/mutationLifecycleWorkflow.ts` applies queue/guard behavior and calls create.
- `src/lib/gateway/agentConfig.ts` (`createGatewayAgent`) performs `config.get` + `agents.create`.

After creation, Studio applies a permissive default capability envelope:
- Commands: `Auto`
- Web access: `On`
- File tools: `On`

Implementation:
- `src/app/page.tsx` (`handleCreateAgentSubmit`) applies `CREATE_AGENT_DEFAULT_PERMISSIONS`.
- `src/features/agents/operations/agentPermissionsOperation.ts` (`updateAgentPermissionsViaStudio`) persists those defaults.

Further capability changes happen from the `Capabilities` tab:
- `src/features/agents/operations/agentPermissionsOperation.ts` (`updateAgentPermissionsViaStudio`)
  - updates per-agent exec approvals (`exec.approvals.get` + `exec.approvals.set`)
  - updates tool-group overrides for runtime, web, and file access (`config.get` + `config.patch` via `updateGatewayAgentOverrides`)
  - updates session exec behavior (`sessions.patch` via `syncGatewaySessionSettings`)

### Runtime Tool Groups Used By Capability Updates

Studio capability updates rely on OpenClaw tool-group expansion (`openclaw/src/agents/tool-policy.ts`), especially:
- `group:runtime` -> runtime execution tools (`exec`, `process`)

Internal mapping detail:
- Command mode `off|ask|auto` maps to role logic (`conservative|collaborative|autonomous`) for policy generation.
- UI exposes direct capability controls, not role labels.

## Studio -> Gateway: “Create Agent” End-to-End

Primary entry points:
- `src/features/agents/operations/mutationLifecycleWorkflow.ts`
- `src/lib/gateway/agentConfig.ts` (`createGatewayAgent`)

Sequence:

```mermaid
sequenceDiagram
  participant UI as Studio UI
  participant L as Create lifecycle
  participant GC as Studio GatewayClient
  participant G as OpenClaw Gateway

  UI->>L: submit({ name, avatarSeed? })
  L->>GC: createGatewayAgent(name)
  GC->>G: config.get
  G-->>GC: { path: ".../openclaw.json", ... }
  GC->>G: agents.create({ name, workspace: "<stateDir>/workspace-<slug>" })
  G-->>GC: { agentId, workspace }
  L-->>UI: completion(agentId)
```

### How Studio Chooses the Default Workspace Path

Studio computes a default workspace path from the gateway’s config path:
- `src/lib/gateway/agentConfig.ts` (`createGatewayAgent`)

Logic:
1. Call `config.get` and read `snapshot.path` (the gateway host config path).
2. Compute `stateDir = dirname(configPath)`.
3. Compute `workspace = join(stateDir, "workspace-" + slugify(name))`.
4. Call `agents.create({ name, workspace })`.

Important: for a remote gateway (EC2), that `workspace` path refers to the gateway host filesystem, not your laptop.

## Studio: Sandbox Env Allowlist Sync (Current Scope)

Create flow does not perform setup writes during initial create anymore. If Studio needs to ensure sandbox env allowlist entries, that behavior should be attached to explicit settings/config operations rather than create-time side effects.

## OpenClaw (Upstream): What `agents.create` Actually Does

Gateway method:
- `openclaw/src/gateway/server-methods/agents.ts` (`"agents.create"`)

Key behaviors:
- Normalizes `agentId` from the provided `name` (and reserves `"default"`).
- Uses the provided `workspace` and resolves it to an absolute path.
- Writes a config entry for the agent (including the workspace dir and agent dir).
- Ensures the workspace directory exists and that bootstrap files exist (unless `agents.defaults.skipBootstrap` is set).
- Ensures the session transcripts directory exists for the agent.
- Writes the config file only after those directories exist (to avoid persisting a broken agent entry).
- Appends `- Name: ...` (and optional emoji/avatar) to `IDENTITY.md` in the workspace.

So: the “workspace” is not a UI-only concept; it is a real directory created on the Gateway host.

## OpenClaw (Upstream): Sandbox Semantics

Sandbox configuration resolution:
- `openclaw/src/agents/sandbox/config.ts` (`resolveSandboxConfigForAgent`)

Sandbox context creation (where workspace selection happens):
- `openclaw/src/agents/sandbox/context.ts` (`resolveSandboxContext`)

Docker mount behavior:
- `openclaw/src/agents/sandbox/docker.ts` (`createSandboxContainer`)

### Sandbox Mode (`sandbox.mode`)

Modes (as implemented upstream):
- `off`: sessions are not sandboxed.
- `all`: every session is sandboxed.
- `non-main`: sandbox all sessions except the agent’s main session key.

The “main session key” comparison is done against the configured main key, with alias-canonicalization:
- Upstream canonicalizes the session key before comparing so that main-session aliases are treated as “main” (see `canonicalizeMainSessionAlias` in upstream sandbox runtime-status).
- If `session.scope` is `global`, the main session key is `global` and `non-main` effectively means “sandbox everything except the global session”.

Upstream implementation reference:
- `openclaw/src/agents/sandbox/runtime-status.ts` (`resolveSandboxRuntimeStatus`)

### Sandbox Scope (`sandbox.scope`)

Sandbox scope controls how sandboxes are shared and therefore what persists between runs:
- `session`: per-session sandbox workspace/container (highest isolation, most churn)
- `agent`: per-agent sandbox workspace/container keyed by agent id (shared across that agent’s sessions)
- `shared`: one sandbox workspace/container shared across everything (lowest isolation)

Upstream implementation reference:
- `openclaw/src/agents/sandbox/types.ts` (`SandboxScope`)
- `openclaw/src/agents/sandbox/shared.ts` (`resolveSandboxScopeKey`)

### Workspace Access (`sandbox.workspaceAccess`)

Upstream behavior (important):
- `rw`:
  - The sandbox uses the **agent workspace** as the sandbox root.
  - PI filesystem tools (`read`/`write`/`edit`/`apply_patch`) operate on the agent workspace.
- `ro`:
  - The sandbox uses a **sandbox workspace** as the sandbox root (writable sandbox dir).
  - The real agent workspace is mounted at `/agent` read-only for command-line inspection.
  - PI filesystem tools are additionally restricted: upstream disables write/edit/apply_patch in this mode (see below).
- `none`:
  - The sandbox uses a **sandbox workspace** as the sandbox root.
  - The agent workspace is not mounted into the container.

Sandbox workspace root default:
- `openclaw/src/agents/sandbox/constants.ts` uses `<STATE_DIR>/sandboxes` (where `STATE_DIR` defaults to `~/.openclaw` unless overridden by `OPENCLAW_STATE_DIR`).

Sandbox workspace seeding:
- When using a sandbox workspace root, upstream seeds missing bootstrap files from the agent workspace and ensures bootstrap exists:
  - `openclaw/src/agents/sandbox/workspace.ts` (`ensureSandboxWorkspace`)
  - The sandbox workspace also syncs skills from the agent workspace (best-effort) in `resolveSandboxContext`.

### Hard Enforcement: Filesystem Tool Root Guard

In upstream OpenClaw, sandboxed filesystem tools are rooted and guarded:
- `openclaw/src/agents/pi-tools.read.ts` (`assertSandboxPath` usage)

Result:
- `read`/`write`/`edit` tools cannot access paths outside the sandbox root, even if the container has other mounts (like `/agent`).

This is intentional: the “filesystem tools” and “exec tool” have different access characteristics inside a sandbox.

## Sandbox Tool Policy (Separate From Per-Agent Tool Overrides)

OpenClaw has an additional sandbox-only tool allow/deny policy:
- `tools.sandbox.tools.allow|deny` (global)
- `agents.list[].tools.sandbox.tools.allow|deny` (per-agent override)

Upstream resolution:
- `openclaw/src/agents/sandbox/tool-policy.ts` (`resolveSandboxToolPolicyForAgent`)

Important nuance:
- If `tools.sandbox.tools.allow` is present and non-empty, it becomes an allowlist.
- If it is set to an empty array, upstream will still auto-add `image` to the allowlist (unless explicitly denied), which often turns “empty” into effectively “image-only”.
- If you want “allow everything” semantics in sandbox policy, prefer `["*"]` over `[]` to avoid the image auto-add corner case.

This is why Studio treats some configs as “broken” and repairs them (see below).

### Policy Layering (Why “Allowed” Can Still Be Blocked)

In a sandboxed session, a tool must pass multiple gates:
- The normal tool policy gates (`tools.profile`, `tools.allow|alsoAllow`, `tools.deny`, plus any provider/group/subagent policies upstream applies).
- The sandbox tool policy gate (`tools.sandbox.tools.allow|deny` resolved for that agent).

So even if Studio enables `group:runtime` for an agent, the tool can still be blocked in sandboxed sessions if sandbox tool policy denies it.

## OpenClaw (Upstream): Tool Availability and `workspaceAccess=ro`

PI tool construction:
- `openclaw/src/agents/pi-tools.ts` (`createOpenClawCodingTools`)

Key enforcement:
- When sandboxed, upstream removes the normal host `write`/`edit` tools.
- It only adds sandboxed `write`/`edit` tools if `workspaceAccess !== "ro"`.
- It disables `apply_patch` in sandbox when `workspaceAccess === "ro"`.

This is why “`workspaceAccess=ro`” means more than “mount it read-only”:
- It is also a tool-policy gate that prevents direct file writes/edits through PI tools.

### Studio Note: Authority Is No Longer Compiled During Create

Studio create flow no longer compiles authority/sandbox settings during initial create.

When capabilities are changed post-create, Studio uses:
- `src/features/agents/operations/agentPermissionsOperation.ts` (`updateAgentPermissionsViaStudio`)

That operation updates:
- exec approvals policy (`exec.approvals.set`)
- per-agent tool overrides (`config.patch` via `updateGatewayAgentOverrides`)
- session exec host/security/ask (`sessions.patch`)

Upstream enforcement is unchanged: `workspaceAccess="ro"` still disables PI `write`/`edit`/`apply_patch` in sandboxed sessions.

## Session-Level Exec Settings (Where `exec` Runs)

Separately from per-agent config and exec approvals, OpenClaw supports per-session exec settings:
- `execHost`: `sandbox | gateway | node`
- `execSecurity`: `deny | allowlist | full`
- `execAsk`: `off | on-miss | always`

These are stored in the gateway session store and mutated with `sessions.patch`:
- Upstream method: `openclaw/src/gateway/server-methods/sessions.ts` (`"sessions.patch"`)
- Patch application: `openclaw/src/gateway/sessions-patch.ts`
- Session entry shape includes `execHost|execSecurity|execAsk`: `openclaw/src/config/sessions/types.ts`

Studio uses these fields to keep “what the UI expects” aligned with gateway runtime:
- Hydration derives the expected values using the exec approvals policy plus sandbox mode:
  - `src/features/agents/operations/agentFleetHydrationDerivation.ts`
  - Special case: if `sandbox.mode === "all"` and there are exec overrides, Studio forces `execHost = "sandbox"` to avoid accidentally running on the host.
- On first send (or when out of sync), Studio patches the session:
  - `src/features/agents/operations/chatSendOperation.ts` calls `syncGatewaySessionSettings(...)`
  - Transport: `src/lib/gateway/GatewayClient.ts` (`sessions.patch`)

Net effect:
- Exec approvals policy controls whether the user will be prompted to approve.
- Session exec settings control where execution happens (sandbox vs host) and the default `security/ask` values for runs.

## OpenClaw (Upstream): Exec Approvals (Policy + Events)

Exec approvals file (defaults upstream):
- `openclaw/src/infra/exec-approvals.ts`
  - default file path: `~/.openclaw/exec-approvals.json`
  - default socket path: `~/.openclaw/exec-approvals.sock`

Gateway methods (persist policy):
- `openclaw/src/gateway/server-methods/exec-approvals.ts`
  - `exec.approvals.get` returns `{ path, exists, hash, file }` (socket token is redacted in responses)
  - `exec.approvals.set` requires a matching `baseHash` when the file already exists (prevents lost updates)

Approval request/resolve + broadcast events:
- `openclaw/src/gateway/server-methods/exec-approval.ts`
  - broadcasts `exec.approval.requested`
  - broadcasts `exec.approval.resolved`

Exec tool approval decision logic:
- `openclaw/src/agents/bash-tools.exec.ts` (calls `requiresExecApproval`, `evaluateShellAllowlist`, etc.)

Studio wiring for policy persistence:
- Studio writes per-agent policy with `exec.approvals.set`:
  - `src/lib/gateway/execApprovals.ts` (`upsertGatewayAgentExecApprovals`)

Studio wiring for UX:
- Studio listens to `exec.approval.requested` and `exec.approval.resolved` and renders in-chat approval cards.
- When the user clicks approve/deny, Studio calls `exec.approval.resolve`.

## Debug Checklist (When Something Feels “Wrong”)

1. Determine if the session is sandboxed and what workspace it is using.
   - Upstream CLI helper: `openclaw sandbox explain --agent <agentId>` (see upstream `src/commands/sandbox-explain.ts`)
2. Confirm what Studio wrote:
   - Agent overrides: `config.get` and inspect `agents.list[]` entry for the agent.
   - Exec approvals: `exec.approvals.get` and inspect `file.agents[agentId]`.
3. If file edits are not happening:
   - Check `sandbox.workspaceAccess` (if `ro`, upstream disables write/edit/apply_patch tools in sandbox).
   - Check tool policy (`tools.profile`, `tools.alsoAllow`, `tools.deny`) for explicit denies on `write`/`edit`/`apply_patch`.
4. If approvals are not showing up:
   - Check exec approvals `security` + `ask`.
   - Check allowlist patterns (a match may suppress prompts when `ask=on-miss`).
5. If the agent can see different files than expected:
   - `workspaceAccess=rw` means “tools operate on the agent workspace”.
   - `workspaceAccess=ro|none` means “tools operate on a sandbox workspace”.
   - `/agent` mount exists only for `workspaceAccess=ro` and is accessible via sandbox exec, not via filesystem tools.

## Studio Post-Create “Permissions” Flows (Not Just Creation)

Studio can also change permissions after an agent exists.

### Capabilities Permissions Updates

Studio’s permissions flow applies coordinated changes from one save action:
- Exec approvals policy (per-agent, persisted in exec approvals file)
- Tool allow/deny for runtime/web/fs groups (`group:runtime`, `group:web`, `group:fs`) in agent config
- Session exec settings (`execHost|execSecurity|execAsk`) via `sessions.patch`

Code:
- `src/features/agents/operations/agentPermissionsOperation.ts` (`updateAgentPermissionsViaStudio`)

UI model:
- Direct controls: `Command mode` (`Off`/`Ask`/`Auto`), `Web access` (`Off`/`On`), `File tools` (`Off`/`On`)
- Create modal remains permission-light (name/avatar only) and create flow immediately applies permissive defaults (`Auto`, web on, file tools on).

Why it matters:
- You can have exec approvals configured but still be unable to run commands if `group:runtime` is denied.
- You can have permissive approvals but still be safe if `execHost` is forced to `sandbox` when sandboxing is enabled.

### One-Shot Sandbox Tool Policy Repair

On connect, Studio scans the gateway config for agents that are sandboxed (`sandbox.mode === "all"`) and have an explicitly empty sandbox allowlist (`tools.sandbox.tools.allow = []`), and repairs those entries by setting:
- `agents.list[].tools.sandbox.tools.allow = ["*"]`

Code:
- Detection + repair enqueue: `src/app/page.tsx` (`repair-sandbox-tool-allowlist`)
- Gateway write: `src/lib/gateway/agentConfig.ts` (`updateGatewayAgentOverrides`)

This exists to prevent sandboxed sessions from effectively losing access to almost all sandbox tools due to an empty allowlist interacting with upstream sandbox tool-policy behavior.