Quarters architecture — Agenxy Development

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. Quarters calls this portable, environment-only mode the baseline.

Launch

quarters enter work follows 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.

The environment and state paths change. UID, groups, permissions, kernel and hardware remain those of the host account.

exec starts the requested executable directly; it does not insert a 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. Its fixed allowlist includes the host PATH, shell, user, locale, terminal, editor, pager, display, Xcode and GnuPG terminal variables. Quarters then adds the space paths. A user may pass another variable by name with --inherit. Its value never appears in diagnostics.

The space’s .local/bin comes first in PATH, so an executable there can shadow a host command with 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 does not start an SSH agent there, so agent-backed SSH remains unavailable until the user starts one. In the portable baseline, OpenSSH also 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. The classification measures compatibility. It makes no confinement claim.

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. The alpha checks the manifest schema and requires its name to match the published directory when it opens a space.

The supervisor holds a shared lock on .active. Removal needs 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, so the user must stop them before removal.

macOS

macOS uses the portable environment baseline and also sets CFFIXED_USER_HOME. Open-source CoreFoundation consults that variable for ordinary processes, but 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. Seatbelt may become an optional backend after a policy review; it cannot define the portable contract.

Linux

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

The host must allow unprivileged user namespaces. Quarters refuses this mode whenever the account has any supplementary group. Only the real UID and primary GID are mapped, so ordinary set-id sudo cannot work inside the view. Setup failures stop the launch.

Landlock could add optional filesystem restrictions on supported kernels. 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 that already runs as the user. Use a VM, container, separate account or operating-system sandbox to contain code.

Copying spaces

Clone, snapshot, template and export need an exclusive lease and a declared copy policy. Runtime sockets and derived caches must be omitted. Databases, agent state, symlinks, modes and extended metadata need deliberate handling. The alpha leaves those commands out until it can make the copy transaction honest.