Container filesystem layout

This page is a consolidated reference for every host-path → container-path mapping that harnessed creates when it launches a stack. Use it to understand where files land inside the container, diagnose mount problems, and author persist: / init: entries correctly.

Two invariants govern all mounts:

1. Profile is assembled ahead of time. Nothing in $XDG_DATA_HOME/harnessed/profiles/<stack>/<harness>/ is resolved, templated, or patched at container start — what harnessed build wrote is what the container sees.
2. No secrets baked into images, and credentials never resolved by harnessed build. Every secret surface (.credentials.json, SSH agent socket, opt-in git credentials) reaches the container only at launch time, as a bind-mount or env-file, and only when the host-side file exists. harnessed build never invokes varlock and never touches any credential at all — see Secrets guide for the deliberate separation between build and launch.

Container identity

The base image (catalog/base/Dockerfile.harnessed-base) sets ENV HOME=/home/harnessed. Every in-container path that starts with $HOME or ~ resolves there.

Per-stack volumes (agent config + tools)

harnessed build and harnessed launch both call _ensure_stack_volumes, which composes two named podman volumes for each (stack, harness) pair and runs recipe tools:/install: scripts into them. The volumes are fingerprint-gated: when the stack’s recipe closure and image are unchanged, the existing volume content is reused and installs are skipped.

Config volume — harnessed-cfg-<harness>-<stack> → $HOME/.claude

Mounted at $HOME/.claude for the claude, omp, and opencode harnesses. This volume is composed, not layered: podman’s copy-up lifts the image’s own ~/.claude content into the volume first, then the assembled profile content (skills, commands, agents, hooks, rules, CLAUDE.md, settings.json) goes on top. The result is a single unified tree — there are no per-subdirectory bind-mounts that could shadow installer-written content.

The fingerprint is written into the volume after a successful populate and checked before the next one. A changed stack starts from an empty config volume (so a removed recipe’s skills and commands do not persist), while the tools volume is kept (mise installs are declarative and incremental).

Tools volume — harnessed-tools-<harness>-<stack> → $HOME/.local

Mounted at $HOME/.local for all harnesses. Receives mise tool installs, pnpm shims, and anything else tools: or install.script writes to ~/.local. Kept across stack changes (re-downloaded only when a tool version or script changes).

.mcp.json — profile bind-mount (claude only)

profiles/ expands to $XDG_DATA_HOME/harnessed/profiles/ (defaults to ~/.local/share/harnessed/profiles/). The .mcp.json is assembled by harnessed build and bind-mounted read-only; it is not part of the config volume because the hatago hub endpoint is resolved at launch time, not at build time.

Project workspace mount

The project directory (or a parent via --mount-folder) is mounted path-mirrored: the same absolute path on the host appears at the same absolute path inside the container. This means the agent sees host paths directly — no path translation needed.

The agent’s working directory (cwd) is set to <project_path> (or --agent-start-folder if specified). With --mount-folder, <mount_path> is a parent of <project_path> — the whole subtree is visible but the agent starts inside the project.

Claude session history mounts (read-write)

These dirs are sourced from the host $HOME/.claude/ and mounted read-write so Claude’s session history, file-tracking, and todos persist across container restarts. Dirs are created on the host automatically if they don’t exist.

Credential mounts

Claude OAuth token

<instance> is harnessed-<stack>-<sha1[:8] of project path>.
$XDG_STATE_HOME defaults to ~/.local/state.

The stub at .claude.json marks hasCompletedOnboarding: true so Claude Code skips its first-run login screen. The real authentication is ~/.claude/.credentials.json (OAuth token) — the stub never contains token material.

omp (Oh My Pi)

SSH signing/auth agent + git config (always forwarded when present)

Forwarded automatically whenever the host agent socket is live — no forward_git_credentials needed. Safe as a default because the agent exposes no key material and gates every sign/auth behind a host-side 1Password approval or YubiKey touch, and the git config is a public signing-key reference, not a secret. All read-only unless noted; only mounted when the host file/socket exists.

git credentials (opt-in, forward_git_credentials: true in stack.yaml)

The secret-bearing surface — only mounted when a stack sets forward_git_credentials: true, and only when the corresponding host file/dir/device exists. All read-only unless noted.

Persist mounts (read-write)

Recipe persist: entries create bind-mounts that survive --fresh restarts. The scope × location axes determine how the host path is constructed. For the full authoring schema (field names, VCS control, valid combinations), see Recipe authoring — persist:.

scope: workspace, location: host — per-worktree, harnessed-managed

persist/ expands to $XDG_DATA_HOME/harnessed/persist/ (defaults to ~/.local/share/harnessed/persist/). The key is the SHA-1[:8] of the resolved launch path — two worktrees of the same git checkout get separate dirs.

scope: project, location: host — cross-worktree, harnessed-managed

The key is derived from git rev-parse --path-format=absolute --git-common-dir — the same path for every worktree of a given checkout, so all worktrees share one host dir. Falls back to the workspace hash (with a warning) when project_path is not inside a git repository. Does not survive an independent git clone of the same repo (git-common-dir changes).

scope: global, location: (not specified) — real host path, allowlisted

The path is mounted path-preserving (host path == container path) so the tool finds its data where it expects. Gated by $XDG_CONFIG_HOME/harnessed/persist-allowlist (default ~/.config/harnessed/persist-allowlist). Several sensitive dirs (~/.ssh, ~/.aws, ~/.gnupg, ~/.config/harnessed, $HOME itself) are hard-denied regardless of the allowlist.

Path-preserving ≠ $HOME-relative. The pod’s $HOME is /home/harnessed, so a host dotdir mounted this way lands at /home/you/.foo, not ~/.foo — a tool that looks under $HOME will not find it. The launcher exports HOST_HOME into the attach shell for exactly this case; point the tool at the mirrored path from the recipe’s init:. The pulumi recipe is the reference implementation (see the Pulumi guide):

persist:
  - scope: global
    path: ~/.pulumi        # the real host dir: credentials.json + the plugin cache

init:
  run: export PULUMI_HOME="$HOST_HOME/.pulumi"

scope: workspace|project, location: in_repo — inside the workspace, no extra mount

No additional bind-mount: the entry lives inside the path-mirrored workspace mount, which is already rw. vcs: ignored causes harnessed to append the entry name to the project’s .gitignore idempotently. vcs: tracked leaves .gitignore untouched.

Init (init:)

init: has no host-side marker (the declarative marker was removed — “Model A”). The run command is sourced inline in the attach shell before the harness starts, on every attach, so it must self-gate cheaply (e.g. bd list >/dev/null 2>&1 || bd init). There are no per-recipe marker files and no transient podman run --rm. See recipe authoring — One-time init.

Misc fixed mounts

See also

• Recipe authoring — persist: and init: schema reference (field names, valid scope/location combos, vcs:, worked examples)
• harnessed-design.md — the design rationale behind the mount model (profile-ahead-of-time, path mirroring, no-host-defaults invariant, secrets threat model)
• research/home-folder-claude-requirements.md — why the specific .claude/ subpaths are forwarded from the host (and which are intentionally excluded)
• Stacks — state.session_state in stack.yaml is a different, stack-level mechanism (where Claude session history volumes land: host vs volume) and is currently unimplemented in the launcher. Do not conflate it with recipe persist: entries, which are fully implemented and described on this page.
• Secrets (varlock + 1Password) — how secrets reach the container at launch time without being baked into the image or the profile