WorkspaceSandboxConfig

The names of the product elements

The name of the type

A config from its JSON (as rw writes it; missing keys take the defaults), validated.

Parse a sandbox profile name into a concrete config.

Valid names (case-insensitive, trimmed):

• permissive or empty string -> Permissive
• locked or locked-down -> LockedDown

Unknown names return Left with an error message instead of silently falling back, so that typos like strict do not weaken the sandbox.

Validates the config; returns Left with error message if invalid.

The longest the runner keeps a request waiting at its command gate - a command for a file mutation to finish, or a file mutation for running commands to end - before refusing it as WORKSPACE_BUSY, having done nothing. A client waiting for a response allows for it on top of the request's own time.

How long after its wait at the gate a file change may still commit. The runner refuses, changing nothing, a change not committed within CommandGateWait + CommitAfterGate of its start, and a client waits longer than that for the response, so a change is never applied after its client gave up on it.

The runner's environment variable holding a whole sandbox config as JSON, in place of a profile (design §4.39).

The runner's environment variable naming programs to add to its profile's allowlist, separated by commas or whitespace (for example sbt); see WorkspaceSandboxConfig.withExtraCommands.

Locked-down sandbox: read-only file ops, no shell, strict limits

The largest limits.maxFileSize the runner keeps: a snapshot holds a file whole in memory, in one array. A config over it is refused by validate, and a runner given one unvalidated uses this instead.

Programs WorkspaceSandboxConfig.withExtraCommands refuses to add: shells, interpreters, launchers and loaders that run another program or code named in their arguments, editors and stream editors that run a command (vim -c '!cmd', GNU sed e), schedulers, package and project runners, notebook tooling, and Windows programs that run another one (#1756, #1761, #1792, #1805, #1845). Any of them would let a command run anything, which is what running commands without a shell prevents.

A name is matched case-insensitively, without a .exe / .com extension and without a trailing version (Python3.12.EXE is python). Interpreter families are matched by prefix as well, since they come in many spellings (python3.7m, python3-dbg, pypy3, luajit, ipython3, jupyter-lab), as is the dynamic loader (ld.so, ld-linux-x86-64.so.2, ld-musl-x86_64.so.1, musl's libc.musl-x86_64.so.1), which runs any program given as its argument. Only ASCII letters, digits, ., _, + and - make a name, so no Unicode look-alike (ｐｙｔｈｏｎ, a Kelvin sign for k) reaches the comparison.

The list is a speed bump, not a boundary: no list names every program that can run another - most tools with a plugin, hook, pager, editor or helper-program option can (the GTFOBins and LOLBAS catalogues list hundreds) - so every name added with WORKSPACE_EXTRA_COMMANDS must be one the host trusts to run any code.

Default permissive sandbox (current behavior). Allows both read-only and write commands.

Read-only command allowlist: safe, non-destructive commands suitable for inspection and navigation. This is the default for new sandbox configs.

The list names programs; the runner also refuses the options through which some of them would write, delete or run another program (find -exec, git -c, sort -o, a second uniq operand, git subcommands other than reads), path arguments that lead outside the workspace, and environment variables other than locale ones. See docs/reference/workspace-sandbox.md#command-policy.

Read-write command allowlist: extends ReadOnlyCommands with commands that can create, modify, or delete files. Opt-in; use when the agent legitimately needs write access to the workspace.