# Quarters architecture > How Quarters redirects user state while keeping the host account and native process model. - **Project:** [Quarters](https://agenxy.org/projects/quarters/) - **Status:** Alpha — v0.1.0-alpha.2 - **Revised:** 2026-08-21 --- 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 /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: ```text ~/.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. Source: https://agenxy.org/projects/quarters/architecture/