| 1 | import type { DocsSandboxDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/sandbox/page.tsx` |
| 5 | * ("Limit what commands can touch"). Checked against docs/SANDBOX.md — which |
| 6 | * describes only behavior wired into the command execution path — and |
| 7 | * docs/CONFIGURATION.md (`sandbox_mode`, `prefer_bwrap`). |
| 8 | */ |
| 9 | export const docsSandbox: DocsSandboxDict = { |
| 10 | metaTitle: "Limit what commands can touch · Codewhale Docs", |
| 11 | metaDescription: |
| 12 | "See which operating-system sandbox wraps shell commands on macOS, Linux, and Windows, turn it on where it is optional, and choose how much a command may write.", |
| 13 | bodyClassName: "text-ink-soft leading-relaxed", |
| 14 | title: "Limit what commands can touch", |
| 15 | lede: |
| 16 | "Approving a command decides whether it runs. A sandbox decides what it can reach once it does. Codewhale uses the operating system's sandbox where one is available and tells you plainly when there is none.", |
| 17 | sections: [ |
| 18 | { |
| 19 | id: "platforms", |
| 20 | title: "Check what your platform provides", |
| 21 | blocks: [ |
| 22 | { |
| 23 | rows: [ |
| 24 | ["macOS", "Seatbelt, automatically, when its startup check succeeds. Commands get broad read access, writes limited by the sandbox mode, and network only when the mode allows it."], |
| 25 | ["Linux", "Bubblewrap, but only if you turn it on (below). Without it, commands run with no OS sandbox."], |
| 26 | ["Windows", "No OS sandbox today. Your approval setting and Windows permissions still apply."], |
| 27 | ["External service", "With `sandbox_backend = \"opensandbox\"`, shell commands run on an OpenSandbox-compatible service you configure; its isolation is that service's to guarantee."], |
| 28 | ], |
| 29 | }, |
| 30 | { p: "Ask Codewhale which one it found:" }, |
| 31 | { code: "codewhale doctor\ncodewhale setup --status", lang: "Terminal" }, |
| 32 | { |
| 33 | p: "Both report the sandbox that is actually available after your settings are applied. Codewhale never counts source code that is not wired in as a sandbox.", |
| 34 | }, |
| 35 | ], |
| 36 | }, |
| 37 | { |
| 38 | id: "linux", |
| 39 | title: "Turn on the Linux sandbox", |
| 40 | blocks: [ |
| 41 | { p: "Install bubblewrap, then opt in with one line in `~/.codewhale/config.toml`:" }, |
| 42 | { |
| 43 | code: `sudo apt install bubblewrap # Fedora: dnf install bubblewrap · Arch: pacman -S bubblewrap |
| 44 | |
| 45 | # ~/.codewhale/config.toml |
| 46 | prefer_bwrap = true`, |
| 47 | lang: "Terminal / config.toml", |
| 48 | }, |
| 49 | { |
| 50 | p: "Codewhale uses `/usr/bin/bwrap` only when that file exists and is executable. Commands then see a read-only view of the system, write only where the sandbox mode allows, and have no network unless the mode enables it.", |
| 51 | }, |
| 52 | ], |
| 53 | }, |
| 54 | { |
| 55 | id: "mode", |
| 56 | title: "Choose how much a command may write", |
| 57 | blocks: [ |
| 58 | { code: 'sandbox_mode = "workspace-write"', lang: "config.toml" }, |
| 59 | { |
| 60 | rows: [ |
| 61 | ["read-only", "Commands can read but not write."], |
| 62 | ["workspace-write", "Commands can write inside the workspace and temporary folders, and nowhere else."], |
| 63 | ["danger-full-access", "No OS sandbox. Use only on a machine or container you are prepared to lose."], |
| 64 | ["external-sandbox", "You are already running inside isolation, so Codewhale adds none of its own."], |
| 65 | ], |
| 66 | codeTerms: true, |
| 67 | }, |
| 68 | { |
| 69 | p: "The first two are enforced only where a sandbox is available — on Linux without bubblewrap, and on Windows, they are settings without an OS wrapper behind them. A repository's own config can make the mode stricter, never looser. For one headless run, pass `--sandbox <mode>` to `codewhale exec`; `--auto` approves tools but never widens the sandbox.", |
| 70 | }, |
| 71 | ], |
| 72 | }, |
| 73 | { |
| 74 | id: "limits", |
| 75 | title: "Know the limits", |
| 76 | blocks: [ |
| 77 | { |
| 78 | list: [ |
| 79 | "Availability is checked before a command starts, but the sandbox can still fail at launch because of host policy or container restrictions.", |
| 80 | "A “Permission denied” from a command is not proof that the sandbox blocked it. Codewhale labels a denial as the sandbox's only when the sandbox itself reported it.", |
| 81 | "No sandbox protects against kernel vulnerabilities or every kind of resource exhaustion.", |
| 82 | ], |
| 83 | }, |
| 84 | ], |
| 85 | }, |
| 86 | ], |
| 87 | next: [ |
| 88 | { |
| 89 | href: "/docs/modes", |
| 90 | label: "Set modes and approvals", |
| 91 | note: "Decide which commands stop for your approval.", |
| 92 | }, |
| 93 | { |
| 94 | href: "/docs/trust", |
| 95 | label: "See what leaves your machine", |
| 96 | note: "What a provider receives, what stays local, and what telemetry sends.", |
| 97 | }, |
| 98 | { |
| 99 | href: "/docs/configuration", |
| 100 | label: "Change settings", |
| 101 | note: "Where these keys live and what a repository may override.", |
| 102 | }, |
| 103 | ], |
| 104 | sourceNote: "Source documents: docs/SANDBOX.md, docs/CONFIGURATION.md · Update docs-map.ts when changing.", |
| 105 | }; |
| 106 |