DSH Settings

This file is the single authoritative source for the rules the DSH harness sandbox runs under in this environment. It follows the literate style of Claude Code Settings: every grant is accompanied by prose naming the command it enables and the failure it prevents, so a reader of a diff can see what is being authorised and why.

Do not edit the generated files by hand. Regenerate them with compass build settings --dsh, which tangles this file into .dsh/ and copies the result to ~/.dsh, where the harness reads it.

~/.dsh holds copies, never symbolic links into this checkout. That is deliberate and it is the whole point of the design: a confined command can write the checkout, so a link would let a confined command widen the sandbox that confines it. With a copy, the live rules sit outside the workspace where the sandbox cannot reach them, and the rules change only when a person runs the deploy.

Via the Build pillar in --direct mode — Emacs only, no cmake or vcpkg:

compass build --direct settings --dsh   # .dsh/, copied to ~/.dsh
compass build --direct settings         # both surfaces

Or via the full-environment CMake target:

cmake --build --preset linux-clang-debug-make --target deploy_dsh_settings

Both invoke projects/ores.lisp/src/ores-build-dsh-settings.el, which tangles this file and then installs the result. Requires Emacs on PATH. It must run outside the sandbox: it writes ~/.dsh, which the sandbox does not grant, precisely so that the rules cannot rewrite themselves. Use dangerouslyDisableSandbox: true on the Bash tool call, or run it from a terminal outside the harness.

The harness runs every bash command under bubblewrap. Three things decide what that sandbox does, and only the last two are ours:

Only file effects are confined. Network access, the process view and unix sockets are outside the sandbox's guarantees, which is why a path list cannot fix a verb that needs a socket (see What cannot be authorised).

The harness has no equivalent of Claude Code's sandbox.excludedCommands. It cannot be told to run a command unconfined as a rule; escalation is per call. The path list is therefore the only lever this repository has over the sandbox, and it is a lever over files, not over commands.

The list is read by the runner below on every confined command, so an edit takes effect on the next command. One absolute path per line; # starts a comment; a leading ~/ is expanded by the runner.

Each entry names the command that needs it and what fails without it. Keep grants to the narrowest path that fixes the failure: a directory grants everything beneath it, and the value of the sandbox is that a mistyped command cannot reach the rest of the host.

The harness invokes this script in place of bwrap, passing the arguments the sandbox profile supplies. It does two things before handing over: it inserts a writable bind for each path in the list above, and it replaces the system ssh include directory with a user-owned copy.

The second job is not about ORE Studio. The sandbox user namespace maps only the calling uid, so every root-owned file reads back as nobody, and OpenSSH refuses to include a configuration file it cannot attribute to root or to the invoking user. That breaks every ssh call, including the ones git makes, so the wrapper binds a user-owned directory over /etc/ssh/ssh_config.d and mirrors the system snippet into it.

#!/usr/bin/env bash
# DSH sandbox runner wrapper for ORE Studio. Run bubblewrap with the profile
# arguments DSH supplies, and add one extra writable bind per path listed in
# the path list, one absolute path per line, '#' comments, a leading ~/
# expanded to the invoking user's home. The binds must follow the profile's
# read-only root mount, so insert them just before the argv separator.
#
# The list is $DSH_SANDBOX_WRITABLE_PATHS when set, else
# ~/.dsh/sandbox-writable-paths, which this script is deployed beside.
#
# It also replaces /etc/ssh/ssh_config.d with a user-owned directory, because
# the sandbox user namespace maps only the calling uid: every root-owned file
# reads back as nobody (65534), and OpenSSH refuses to Include a config file it
# cannot attribute to root or the invoking user.
#
# Only bash commands receive these grants: the write and edit tools are fenced
# by the in-process policy, which knows only the workspace root and the
# platform temp areas. Use a command for anything under a path listed here.
set -euo pipefail

readonly list_file="${DSH_SANDBOX_WRITABLE_PATHS:-$HOME/.dsh/sandbox-writable-paths}"

# The shared bare repository every ORE Studio worktree points at, kept as the
# fallback when the list file is absent so an unconfigured host still works.
readonly fallback_path="$HOME/Development/OreStudio/ores.git"

# The replacement ssh include directory, and the systemd snippet mirrored into
# it so the .host and machine/* aliases survive the replacement.
readonly ssh_include_dir="${DSH_SSH_INCLUDE_DIR:-$HOME/.dsh/ssh-config.d}"
readonly ssh_include_src=/usr/lib/systemd/ssh_config.d/20-systemd-ssh-proxy.conf

# Expand a leading ~/ here rather than in the shell that reads the list, since
# the list is data and the host that reads it owns the home it means.
expand_home() {
  case "$1" in
    "~/"*) printf '%s\n' "$HOME/${1#\~/}" ;;
    *)     printf '%s\n' "$1" ;;
  esac
}

paths=()
if [ -f "$list_file" ]; then
  while IFS= read -r line; do
    line="${line%%#*}"
    line="${line#"${line%%[![:space:]]*}"}"
    line="${line%"${line##*[![:space:]]}"}"
    [ -n "$line" ] && paths+=("$(expand_home "$line")")
  done < "$list_file"
else
  paths=("$fallback_path")
fi

grants=()
for path in "${paths[@]}"; do
  # bwrap refuses a bind whose source is missing, so skip it rather than let
  # one stale list entry break every confined command.
  [ -e "$path" ] && grants+=(--bind "$path" "$path")
done

# The sandbox user namespace maps only the calling uid, so every root-owned
# file reads back as nobody. ssh refuses to Include a config file whose owner
# is neither root nor the invoking user, which breaks every ssh call on the
# system include directory. A user-owned directory bound over it leaves ssh
# with only files it accepts. A host that cannot provide that directory keeps
# the system one, rather than losing every confined command.
if [ -d /etc/ssh/ssh_config.d ] && mkdir -p "$ssh_include_dir" 2>/dev/null; then
  if [ -r "$ssh_include_src" ] &&
     ! cmp -s "$ssh_include_src" "$ssh_include_dir/20-systemd-ssh-proxy.conf"; then
    cp -f "$ssh_include_src" "$ssh_include_dir/20-systemd-ssh-proxy.conf" || true
  fi
  grants+=(--bind "$ssh_include_dir" /etc/ssh/ssh_config.d)
fi

granted=0
for arg in "$@"; do
  if [ "$arg" = "--bind" ]; then granted=1; fi
done

out=()
for arg in "$@"; do
  if [ "$arg" = "--" ] && [ "$granted" = 1 ] && [ "${#grants[@]}" -gt 0 ]; then
    out+=("${grants[@]}")
  fi
  out+=("$arg")
done

exec /usr/bin/bwrap "${out[@]}"

The runner is selected by the harness configuration, not by this document. The home patch layer applies to every profile and is where the selection belongs:

- id: sandbox
  config:
    runnerCommand:
      - /home/marco/.dsh/bin/dsh-bwrap-writable-ores.sh
    runnerFailureSignatures:
      - "bwrap: "

This file also carries a block the harness manages itself, so the deploy neither writes nor owns it: it copies the runner and the path list, then reports whether the patch selects that runner. Add the block by hand if it reports that it does not, or if the harness rewrites the file and drops it.

A path list cannot grant a socket, and several compass verbs need one. This is a limit of the mechanism, not a gap in the list.

Two harnesses run agents in this checkout, and each has its own settings with its own mechanism:

They must agree on what they grant. When they disagreed over the sccache directory, nothing reported it; the two files were edited at different times and the divergence surfaced only as a build failure. A change to either is a security-relevant change and belongs in a pull request, where the diff shows exactly what is newly authorised.

• Claude Code Settings – the sibling surface, and the pattern this file follows.
• Builds can run outside the sandbox – why a build may leave the sandbox, and the standing authorisation for it.