docs: document project-level sandbox approval gate

Author: jkyberneees

docs/CHEATSHEET.md

@@ -229,6 +229,8 @@ Flags: `--sandbox`, `--sandbox-image`, `--sandbox-network`, `--sandbox-readonly`
 
 Env vars: `ODEK_SANDBOX=true`, `ODEK_SANDBOX_IMAGE`, `ODEK_SANDBOX_NETWORK`, etc.
 
+> **Project config approval:** sandbox knobs set in `./odek.json` (`sandbox_env`, `sandbox_image`, `sandbox_network`, `sandbox_volumes`) require an interactive approval prompt. Use `ODEK_APPROVE_PROJECT_SANDBOX=1` in CI/scripts, or set sandbox config via `~/.odek/config.json` / env vars / CLI flags instead.
+
 Default network: `bridge` (internet access). Set `none` for air-gapped execution.
 
 ## Telegram Bot
@@ -289,6 +291,7 @@ odek mcp                                    # stdio transport
 | `ODEK_SANDBOX_MEMORY` | sandbox_memory |
 | `ODEK_SANDBOX_CPUS` | sandbox_cpus |
 | `ODEK_SANDBOX_USER` | sandbox_user |
+| `ODEK_APPROVE_PROJECT_SANDBOX` | auto-approve project-level sandbox config (CI) |
 | `ODEK_SYSTEM` | system |
 | `ODEK_NO_COLOR` | no_color |
 | `ODEK_NO_AGENTS` | no_agents |

docs/CLI.md

@@ -296,6 +296,8 @@ Use `odek skill reset-skips` to clear the skip list and re-enable suppressed sug
 
 `odek serve` enables `--sandbox` by default. `odek run` and `odek repl` keep sandbox opt-in but print a startup warning when running unsandboxed. Set `ODEK_SUPPRESS_SANDBOX_WARNING=1` to silence the warning if you've made an informed decision.
 
+**Project-level sandbox approval:** if `./odek.json` sets `sandbox_env`, `sandbox_image`, `sandbox_network`, or `sandbox_volumes`, odek prompts for approval before applying them. In CI or scripted invocations, set `ODEK_APPROVE_PROJECT_SANDBOX=1` to auto-approve, or place sandbox config in `~/.odek/config.json` / `ODEK_*` env vars / CLI flags instead, which do not require approval.
+
 ## Audit log
 
 `odek audit` reads the per-session prompt-injection audit log written under `<sessions>/audit/<id>.json`. Every time the agent ingests externally-sourced content (browser fetch, file read, MCP tool response, audio transcript) the log records:

docs/CONFIG.md

@@ -122,6 +122,7 @@ Every config knob has a `ODEK_*` counterpart:
 | `ODEK_SANDBOX_MEMORY` | `--sandbox-memory` | string |
 | `ODEK_SANDBOX_CPUS` | `--sandbox-cpus` | string |
 | `ODEK_SANDBOX_USER` | `--sandbox-user` | string |
+| `ODEK_APPROVE_PROJECT_SANDBOX` | — | bool | approve project-level `./odek.json` sandbox config without prompting |
 | `ODEK_MAX_TOOL_PARALLEL` | `max_tool_parallel` | int |
 | `ODEK_MEMORY_EXTENDED_ENABLED` | `--memory-extended-enabled` | bool |
 | `ODEK_MEMORY_EXTENDED_MAX_SIZE_MB` | `--memory-extended-max-size-mb` | int |
@@ -828,6 +829,11 @@ odek run "list files"
 echo '{"max_iterations": 30}' > ./odek.json
 odek run "quick status"
 
+# Project-level sandbox knobs require explicit approval (or the CI bypass)
+# because they can read host env vars and pick arbitrary images/networks.
+echo '{"sandbox": true, "sandbox_env": {"X": "${HOME}"}}' > ./odek.json
+ODEK_APPROVE_PROJECT_SANDBOX=1 odek run "run untrusted script"
+
 # Env var override for one-off
 ODEK_SANDBOX=true odek run "run untrusted script"
 

docs/SANDBOXING.md

@@ -68,6 +68,46 @@ All sandbox settings are available in `~/.odek/config.json`, `./odek.json`, `ODE
 > or symlinks are rejected. Relative paths are resolved relative to the working
 > directory and must stay inside it.
 
+## Project-level sandbox approval
+
+`./odek.json` can be shipped by any repository the agent runs in. Because
+project-level sandbox knobs (`sandbox_env`, `sandbox_image`, `sandbox_network`,
+`sandbox_volumes`) can exfiltrate host secrets via `${VAR}` interpolation, pull
+an attacker-controlled image, or widen network access, odek requires explicit
+operator approval before applying them.
+
+When a project requests any sandbox override, odek prints a warning and prompts:
+
+```text
+WARNING: project config (./odek.json) requests sandbox overrides:
+  image:   alpine:latest
+  network: bridge
+  env:     X
+  ⚠️  sandbox_env values contain ${...} interpolation against host environment variables
+
+Allowing this means code in the sandbox can read workspace files and,
+depending on network mode, contact external hosts.
+
+Approve? [y = once / t = trust this project / N]
+```
+
+Approval options:
+
+- `y` / `yes` — approve once for this run.
+- `t` / `trust` — persist approval for this project/sandbox fingerprint in
+  `~/.odek/project_sandbox_approvals.json`.
+- `N` / empty — abort.
+
+For non-interactive use (CI, cron, scheduled tasks), set:
+
+```bash
+export ODEK_APPROVE_PROJECT_SANDBOX=1
+```
+
+Operator-controlled sources (`~/.odek/config.json`, `ODEK_*` env vars, and CLI
+flags) do not require approval — only values coming from the project-level
+`./odek.json` are gated.
+
 ### Env var examples
 
 ```bash

docs/SECURITY.md

@@ -351,6 +351,17 @@ exceed the cap are rejected before they are written.
 
 These fields can only be set from operator-controlled sources: `~/.odek/config.json` (and `ODEK_TELEGRAM_*` env vars for `telegram`, `ODEK_GUARD_*` env vars for `guard`).
 
+### 18a. Project-level sandbox config approval
+
+`./odek.json` can also set sandbox knobs (`sandbox_env`, `sandbox_image`, `sandbox_network`, `sandbox_volumes`). Rather than silently rejecting them, odek gates them behind explicit operator approval, mirroring the MCP-server approval flow:
+
+- Interactive TTY prompt (`y` = once, `t` = trust this project, `N` = deny).
+- Persistent per-project approvals stored in `~/.odek/project_sandbox_approvals.json`.
+- `ODEK_APPROVE_PROJECT_SANDBOX=1` bypass for CI/non-interactive use.
+- Non-TTY runs without the bypass fail closed.
+
+This prevents a malicious repo from exfiltrating host secrets via `${VAR}` interpolation in `sandbox_env`, pulling an attacker-controlled image, or widening the container's network access without the operator's consent.
+
 ### SSRF guard and configured-backend allowlist
 
 The `browser`, `http_batch`, and `web_search` tools use a shared SSRF / DNS-rebinding dial guard (`cmd/odek/ssrf_guard.go`). After the policy gate classifies a hostname as `network_egress`, the guard resolves the name itself and refuses any answer that points at a loopback, RFC1918, RFC4193, link-local, or metadata IP. It then pins the dial to the validated IP so the kernel cannot re-resolve to a different address.