Quarters architecture

The kernel decides file access by comparing a process’s UID and groups with file ownership, modes and ACLs. Programs usually learn where to keep user state from HOME, XDG variables or a tool-specific setting. Quarters changes those paths for one process tree. The process keeps its real UID and groups. This portable, environment-only mode is the baseline.

Launch

quarters enter work runs four steps before the shell starts.

1Open the spaceRead its manifest; require the schema and directory name to match.

2Build the environmentKeep the host PATH and approved session values, then set the space paths.

3Hold the leaseBlock removal before the supervised process starts.

4Start the programExecute the native shell or command directly, with no guest system.

Changed: environment and state paths. Host account: UID, groups, permissions, kernel and hardware.

exec starts the requested executable directly, with no shell. host clears the Quarters paths and restores the host HOME, PATH, temporary directory and XDG runtime directory captured at launch.

Environment construction

Quarters clears the inherited environment. The fixed allowlist includes the host PATH, shell, user, locale, terminal, editor, pager, display, Xcode and GnuPG terminal variables. Space paths are then added. --inherit passes another variable by name. Its value never appears in diagnostics.

The space’s .local/bin is first in PATH. An executable there can shadow a host command of the same name.

The baseline redirects:

HOME and the XDG config, data, state, cache and runtime roots
zsh and bash startup files and history
Git, GitHub CLI, GnuPG, tmux, Cargo, npm and uv state
supported Codex, Claude Code and OpenCode paths
temporary files and the expected SSH-agent socket

Git receives a per-space global config that first clears inherited credential helpers. SSH_AUTH_SOCK points to a short per-space path. The alpha starts no SSH agent there: agent-backed SSH is unavailable until the user starts one. Baseline OpenSSH needs its config passed with ssh -F <space>/home/.ssh/config. Linux home view puts that file at the default passwd-home path.

doctor classifies each integration by how it finds state: HOME or XDG, an explicit override, an invocation adapter, or host-bound state or authority. This measures compatibility, not confinement.

State on disk

The default store is private to the current user:

~/.quarters/
  spaces/
    work/
      .quarters.json
      .active
      home/
        .config/
        .local/{bin,share,state}/
        .cache/
        .gitconfig
        .ssh/config
        .gnupg/
  trash/

Creation builds the complete space in owner-only directories beside the final path, syncs its control files and publishes it with one rename. Readers never see a half-created space. Opening a space, the alpha checks the manifest schema and requires its name to match the published directory.

The supervisor holds a shared lock on .active. Removal requires the exclusive lock, renames the selected space into trash, then deletes that retired path. A detached child, tmux server or agent can outlive the supervisor. Portable process inspection cannot prove that every such descendant has stopped. The user must stop them before removal.

macOS

macOS uses the portable baseline and sets CFFIXED_USER_HOME. Open-source CoreFoundation consults that variable for ordinary processes. Apple does not document it as a public contract. Quarters treats it as a compatibility aid.

macOS has no per-process mount namespace. A program that asks the user database for its home can still find the real path. Keychain, TCC, Secure Enclave, app containers and login services also keep the host identity.

Linux

Linux uses the same baseline. Opt-in --home-view adds a user namespace and a private mount namespace, then bind-mounts the space home over the passwd home. Programs that ignore HOME see the space path at the usual location.

Required: the host allows unprivileged user namespaces. Quarters refuses this mode when the account has any supplementary group. Only the real UID and primary GID are mapped; ordinary set-id sudo cannot work inside the view. Setup failures stop the launch.

The current build does not present a changed home view as filesystem confinement.

Authority boundary

Every child keeps the host account’s authority. It can open an absolute path into the real home, reach same-user services and use the host network and devices. In baseline mode, sudo follows host policy and leaves the space.

Quarters reduces accidental state reuse. It cannot contain hostile code running as the user. Containment requires a VM, container, separate account or operating-system sandbox.

Copying spaces

Clone, snapshot, template and export are unavailable in the alpha. A copy must hold an exclusive lease and follow a declared copy policy. Runtime sockets and derived caches must be omitted. Databases, agent state, symlinks, modes and extended metadata need deliberate handling.