AgentOS User Handbook

Executive summary

This handbook is derived primarily from the AgentOS Technical Requirements Specification, dated August 24, 2026, which defines AgentOS as a human-and-agent Linux workstation operating system built around a Fedora Linux 44 userspace, Btrfs-governed persistent state, a small trusted Control Host, persistent human staging Workspaces, system-container execution for humans, and KVM/QEMU microVM isolation for untrusted agents. The central design principle is that a process may have a complete writable environment—even root inside that environment—without gaining authority to make its changes the machine's accepted state or to control the physical host. fileciteturn0file0

AgentOS is therefore best understood as two systems working together. The Control Host owns physical-machine authority: the kernel, boot chain, TPM, encrypted storage unlock, physical disks, physical networking, firmware, hardware-facing devices, AgentOS governance, trusted authorization UI, recovery, lineage references, and acceptance policy. A World contains ordinary Linux computing state such as software, /etc, user files, services, package state, and application data. A Workspace is a writable future derived from a World or checkpoint. Human work normally occurs in a persistent staging Workspace; untrusted agents receive automatically created feature Workspaces running behind a KVM/QEMU boundary. fileciteturn0file0

The most important operational distinction for an end user is staging versus accepted history. Your ordinary desktop is persistent and writable; you do not have to begin a transaction before editing files, installing packages, running databases, or doing development work. Those changes survive Workspace restarts and physical reboots. They do not, however, modify already accepted history. Acceptance occurs later through governed promotion, which constructs, validates, seals, and atomically references a new immutable accepted object while retaining the predecessor. fileciteturn0file0

For agent-assisted work, AgentOS automatically creates a feature Workspace from an exact checkpoint. That Workspace receives only the state domains, devices, networking, and credentials policy permits. The default agent-standard profile uses KVM/QEMU specifically because the TRS treats hostile guest code as part of its threat model. A faster agent-fast container profile exists only for explicitly trusted or low-risk agents and must be visibly identified as weaker isolation. QEMU's current security documentation likewise treats KVM-accelerated supported machine types such as microvm and q35 on x86_64 as virtualization configurations intended to provide guest isolation, while recommending least privilege around the QEMU process itself. fileciteturn0file0 citeturn4view3

The reference platform is explicitly specified, rather than unspecified: x86_64, UEFI, Secure Boot for secure-daily-driver conformance, TPM 2.0 for the default measured-unlock/device-key model, KVM-capable hardware virtualization, LUKS2 encryption, Btrfs authoritative World storage, a Wayland-capable graphics stack, and Control Host ownership of physical networking. An IOMMU should be enabled and becomes mandatory before direct device assignment. SSD/NVMe storage is recommended. The TRS does not prescribe minimum RAM, minimum disk capacity, exact GPU models, exact supported Wi-Fi chipsets, or a minimum CPU generation. fileciteturn0file0

The desktop itself is not optional, although its exact shell is unspecified. The TRS requires a usable Wayland desktop and release qualification for GPU acceleration, multi-monitor operation, audio, camera, microphone, USB, Bluetooth, Wi-Fi experience, VPN, suspend-to-RAM, display hotplug, clipboard, notifications, screen locking, accessibility, browser use, IDEs, rootless containers, and supported graphics/development workloads. The specification does not name GNOME, KDE Plasma, or another particular desktop environment, so this handbook does not assume one. fileciteturn0file0

Package management is also specified, not unspecified. Ordinary World administration includes RPM/DNF, with operations such as sudo dnf install ... and sudo dnf remove ...; AgentOS additionally requires an RPM/DNF semantic provider so package changes can be reconstructed, integrated, validated, and promoted safely. Fedora's current DNF5 documentation defines package installation, removal, upgrade, groups, history, replay, and related operations, with /etc/dnf/dnf.conf as the standard global configuration file. fileciteturn0file0 citeturn1search7turn5search10

A crucial documentation caveat is that the TRS defines a typed Control API, but it does not specify a complete final agentos shell-command grammar. Operations such as workspace.checkpoint, lineage.promote, history.inspect, backup.create, and control.update are normative API operation names; they must not be misrepresented as literal shell commands until the implementation defines the client syntax. The one concrete recovery command explicitly shown in the TRS is agentos recover rebuild-catalog. This handbook therefore distinguishes real Fedora/Linux commands from AgentOS API operation names rather than inventing commands that may not exist. fileciteturn0file0

Concepts, trust boundaries, roles, and state

AgentOS deliberately separates Control Host, World, Workspace, and Execution because they answer different questions. The Control Host is the real physical machine and security authority. A World is a durable logical composition of state. A Workspace is a mutable descendant of a World or checkpoint. Execution is the mechanism used to run a Workspace. A Btrfs snapshot relationship therefore tells you about storage ancestry but does not tell you whether code is isolated by a container or a hardware virtualization boundary. fileciteturn0file0

Accepted history is logically immutable. AgentOS-supported operations must never mutate an accepted object in place. Instead, acceptance creates a new object and advances a lineage reference using compare-and-swap. This is not a claim that a Btrfs read-only subvolume is physically write-once media; the integrity model combines authorization separation, immutable manifests, signed commitments, backup, and optionally external witnessing. fileciteturn0file0

Staging is where humans live. Every lineage has persistent staging, with main as the default lineage. Human changes survive restarts until explicitly reset, replaced, or deleted. Ordinary work therefore feels like conventional Fedora: editing files, running applications, installing development tools, changing /etc, enabling services, and using sudo all happen normally within staging. fileciteturn0file0

Features are isolated futures. When an agent begins a feature, AgentOS first seals an exact checkpoint, composes only granted state domains, creates writable descendants, assigns fresh identity, issues a session credential, and only then starts execution. Changes made later to staging do not leak silently into an already-created feature; updating the feature from newer staging requires an explicit refresh or rebase. fileciteturn0file0

Root means different things in different planes. Root inside a World is ordinary Linux root for that World. It may install packages, edit World /etc, create users, manipulate services, run databases, or install toolchains. It must not thereby gain access to the physical ESP, raw storage, host kernel, host TPM, physical network control, Control Host SELinux policy, firmware, Control Host D-Bus, host container-engine sockets, or AgentOS control authorization. fileciteturn0file0

The system therefore has two independent identity planes:

The Control identity plane must remain independent of /etc/passwd, /etc/group, /etc/shadow, PAM, World sudo policy, or World SSH configuration. This separation means, for example, that restoring a historical World containing an old account database cannot restore a previously revoked AgentOS Control Host administrator. fileciteturn0file0

The reference release specifies one machine owner/control principal. Additional Unix users may exist inside Worlds, but independent multi-owner governance and competing owners of separate staging lineages are explicitly outside the reference-release scope. fileciteturn0file0

AgentOS exposes these execution profiles:

These are normative profiles from the TRS. The UI must not silently substitute agent-fast when agent-standard was requested because the former shares the Control Host kernel and therefore provides a weaker isolation boundary. fileciteturn0file0

QEMU's current security model reinforces the rationale for that distinction: its supported virtualization use case assumes hardware acceleration such as KVM, treats the guest as untrusted, and emphasizes guest isolation, least privilege, resource limits, namespaces, MAC confinement, and seccomp. citeturn4view3

State is divided by lifecycle rather than by a single root filesystem. A World is composed of domains:

Unknown ordinary persistent content defaults conservatively to versioned state unless policy explicitly excludes it. fileciteturn0file0

This composition is why a conventional path can remain familiar while having explicit history semantics:

SYSTEM object             -> /
USER/alice object         -> /home/alice
SERVICE/postgres object   -> /var/lib/postgresql
CACHE/alice               -> /home/alice/.cache
IDENTITY injection        -> /etc/machine-id and related runtime identity
EPHEMERAL                 -> /run and selected temporary paths

These mappings are directly described by the TRS. Domain boundaries are governed storage topology, not arbitrary folders that users should convert into Btrfs subvolumes themselves. Reclassifying a state domain is a migration requiring policy, data-placement, provenance, mount-topology, and recovery updates. fileciteturn0file0

Installation, first start, updates, and user interface

A conforming installer must do substantially more than a conventional Fedora installation. It must verify installation media and Secure Boot prerequisites; detect KVM and TPM 2.0; establish Control Host storage and separate World Btrfs storage; create LUKS2 encryption; enroll TPM2-backed unlock; generate and require verification of an independent recovery key; back up the LUKS header; install the signed image-based Control Host and independent recovery environment; initialize the AgentOS object store, main lineage, and staging/main; create both the machine-owner Control identity and compatible World owner account; generate unique Control Host and staging identities; and complete an end-to-end integrity check. Hardware that does not meet secure-daily-driver prerequisites must be reported explicitly rather than silently receiving a weaker threat model. fileciteturn0file0

Before installation, verify the following reference requirements:

Recovery material is a first-class installation output. TPM-based convenience must never become the only way to decrypt the machine. Keep the independent recovery key somewhere that does not depend on the installed World. The installer is required to make you verify that recovery material and preserve a protected LUKS header backup. During future PCR-policy changes, a known-working unlock method must remain until the replacement boot has succeeded and been blessed. fileciteturn0file0 systemd's TPM architecture supports measurements of multiple boot phases into PCRs, which is why legitimate boot-chain and firmware changes require deliberate lifecycle handling rather than treating TPM enrollment as static forever. citeturn0search15

Suggested installation screenshots for the finished product documentation:

Those screens are documentation recommendations, not UI layouts required verbatim by the TRS; the underlying installer outcomes are normative. fileciteturn0file0

First login. Normal daily interaction should enter the persistent human staging environment rather than exposing a general-purpose Control Host desktop. The Control Host should keep conventional interactive userspace to a minimum; daily applications run in Worlds. The contained desktop must nevertheless behave like an ordinary Fedora workstation, including browser, IDE, Git, development tools, audio, graphics, peripherals, and other qualified desktop workflows. fileciteturn0file0

Trusted prompts look different for a reason. A World desktop cannot be a trustworthy place to approve operations such as promotion, firmware updates, host-device grants, secret grants, raw egress, trust-root changes, final garbage collection, or Control Host administration, because a compromised World could imitate the pixels. AgentOS therefore requires a Control Host-owned overlay plus a host-reserved secure-attention gesture that allows the owner to identify the authentic trusted surface. Each sensitive prompt must state the authenticated Control principal, requesting Workspace and session, requested capability, target resource, effect classification, lease duration, and whether authorization survives restart. fileciteturn0file0

The exact secure-attention key combination, desktop shell, panel design, Settings application, and notification appearance are unspecified in the TRS. Product documentation for a concrete implementation must fill those items in before distribution to end users. fileciteturn0file0

There are two distinct update paths. A World is conventional Fedora userspace: software updates made with RPM/DNF become staging state and can later enter accepted history through AgentOS governance. The Control Host, in contrast, is delivered as a signed image-based system using bootc as the reference update technology, with inactive deployment, boot-counted trial, health gates, boot blessing, and fallback. World promotion must never install a World-supplied kernel into the physical Secure Boot chain. fileciteturn0file0

For ordinary World updates, a typical human staging operation is:

# Run inside your human staging World.
sudo dnf upgrade --refresh

Package changes remain ordinary writable staging state until governed acceptance. DNF5 is the current Fedora-family package-management stack documented for installation, removal, upgrade, repository operations, history, and replay. fileciteturn0file0 citeturn1search7turn5search15

Do not treat dnf system-upgrade to a future Fedora major release as an implicitly supported AgentOS operation. Although DNF5 itself supplies a major-release system-upgrade command, the TRS normatively defines Fedora 44 as the World baseline and requires tracking the supported Fedora 44 update stream; it does not define a Fedora 44→45 AgentOS persistent-format/provider transition. Such a major-version migration therefore requires explicit AgentOS release documentation before being treated as supported. fileciteturn0file0 citeturn1search11

Control Host updates should normally be initiated through the AgentOS Control UI/API operation:

operation: control.update

The exact user-facing CLI syntax is unspecified. At the underlying reference-technology layer, bootc supports checking, fetching and applying image updates separately (bootc upgrade --check, bootc upgrade, and bootc upgrade --apply), but AgentOS adds its own trust verification, inactive-deployment, health-gate, schema-compatibility, boot-counting and blessing requirements; users should not bypass that governance by directly manipulating the host deployment. fileciteturn0file0 citeturn1search15turn0search5

systemd's automatic boot assessment supports counters that reduce the preference of repeatedly failing entries and a blessing mechanism that marks a successful boot as good; AgentOS uses those primitives as part of a broader Control Host rollback protocol. citeturn0search5 fileciteturn0file0

Hibernation is intentionally not available in the reference release. Suspend-to-RAM may be supported and is part of desktop qualification. fileciteturn0file0

Daily workstation operation

For day-to-day work, think of staging/main as your normal Fedora workstation. It is already writable, it persists across reboot, and you do not need to create or commit a transaction before editing code, installing packages, modifying configuration, running a database, or using an IDE. Governance happens around checkpoints, agent branches, integration, promotion, history, external effects, and physical-host authority—not around every ordinary file write. fileciteturn0file0

Ordinary World administration. These are explicitly intended to work:

# Install software.
sudo dnf install git ripgrep

# Remove software.
sudo dnf remove ripgrep

# Update packages within the supported Fedora 44 update stream.
sudo dnf upgrade --refresh

# Edit World-local system configuration.
sudoedit /etc/example.conf

# Start a World-local service.
sudo systemctl start example.service

# Enable it for future Workspace starts.
sudo systemctl enable example.service

The TRS explicitly identifies DNF installation/removal, /etc editing, World-user creation/removal, systemctl enable, systemctl start, make install, development toolchains, local databases, rootless or World-local containers, and ordinary World services as normal World-root activities. fileciteturn0file0 DNF5's official command set includes install, remove, upgrade, history and related transaction operations; its global configuration is normally /etc/dnf/dnf.conf. citeturn1search7turn1search2turn5search10

Package management and AgentOS history are complementary. Running DNF is not itself promotion. An installed package modifies your current staging Workspace. When an agent feature or a selective promotion later includes package state, AgentOS's RPM/DNF provider must understand more than the visible package name: exact reconstruction records package identity including NEVRA, package digest, signature identity, repository identity and metadata, dependency resolution, scriptlet/triggers, transaction ordering, and resulting package database state. The provider distinguishes exact replay of retained artifacts from semantic replay against currently approved repositories. fileciteturn0file0

The distinction matters because upstream DNF itself can record/replay transactions, but AgentOS attaches additional World ancestry, governance, provenance, provider and candidate-validation semantics around package changes. DNF5's replay command likewise expects stored transaction information and can reject replay when the target package state differs. citeturn1search8

File layout and configuration reference.

The TRS gives the following example, not a promise that every implementation exposes these physical paths to users, for trusted Control Host persistent storage:

/var/lib/agentos/
├── db/
│   └── control.db
├── objects/
│   └── sha256/...
├── ledger/
│   ├── segments/
│   └── roots/
├── attestations/
├── operations/
├── policies/
├── providers/
├── security/
└── recovery/

The SQLite database is an index and durable-operation coordinator, not the sole historical authority; authenticated immutable objects outside the DB must preserve enough information for catalog reconstruction after database loss. fileciteturn0file0

Services and daemons inside a World behave like ordinary systemd services. Package installation, systemctl enable, systemctl start, World-local database operation, and service configuration are intended compatibility targets. fileciteturn0file0 A typical troubleshooting session is therefore:

sudo systemctl status postgresql.service
sudo journalctl -u postgresql.service
sudo journalctl -u postgresql.service -f

journalctl reads systemd journal records, can filter by unit, can restrict output to a boot, and supports -f/--follow for live output. Access to system logs depends on ordinary journal permissions. citeturn3search1

World-level logs and AgentOS provenance are different systems. An application log answers "what did the application report?" The AgentOS mutation ledger records governance and causal evidence such as Workspace, principal, session, operation type, capability grants/use, affected resources, external effects, checkpoints and attestations. Sensitive audit payloads—potentially including commands, paths, process environments, prompts or diagnostics—must be separable from immutable commitments and independently encrypted so payload retention can expire without destroying the audit commitment. Full prompt or conversation capture is opt-in rather than mandatory. fileciteturn0file0

Process management stays within the Workspace boundary. Ordinary Linux process tools may be used inside a World; systemd and cgroup v2 provide the process and service hierarchy AgentOS builds upon. AgentOS also uses cgroups at a higher level for Workspace resource limits and coordinated checkpoint barriers. A process in one Workspace must not gain authority over Control Host processes or another feature merely because it is root in its own environment. fileciteturn0file0 The Linux cgroup v2 interface supports freezing a cgroup and reporting when the frozen state has taken effect, a primitive the TRS uses for coordinated state boundaries. citeturn3search6

Reboot semantics are intentionally scoped.

sudo systemctl reboot

When invoked inside a World, this is required to restart that Workspace, not the physical machine. A physical reboot is a host effect and requires the typed AgentOS host operation/capability represented by HOST_REBOOT. fileciteturn0file0

A normal physical reboot request therefore conceptually passes through:

requesting World or user
        |
        v
typed AgentOS host request
        |
        v
trusted authorization/policy
        |
        v
Control Host physical reboot

The exact CLI syntax for RequestHostReboot/HOST_REBOOT is unspecified in the TRS. fileciteturn0file0

Networking requires special attention. Every physical network interface belongs exclusively to the Control Host. A system-container Workspace receives a virtual Ethernet interface/network namespace; a microVM receives a virtual NIC such as virtio-net. Host policy controls forwarding, DNS, inbound publication, raw egress and broker endpoints. fileciteturn0file0

AgentOS classifies outbound networking semantically:

agent-standard defaults to brokered read access plus explicitly granted typed effects; human-default may receive raw networking by default. Merely allowing TCP/HTTPS to a destination is never represented as semantically read-only because encrypted traffic might contain a purchase, deletion, deployment, Git push, payment or other remote mutation. fileciteturn0file0

NetworkManager is the reference implementation for physical host networking, and upstream nmcli can create, modify, activate and deactivate NetworkManager connection profiles. However, because AgentOS requires physical NIC ownership to remain in the Control Host, you should not assume that nmcli run as World root controls the laptop's Wi-Fi radio or physical Ethernet device. Physical connection-profile changes should be mediated by the trusted AgentOS UI/broker, whose host API includes a typed RequestNetworkProfile operation. The concrete AgentOS networking CLI/UI workflow is not defined by the TRS. fileciteturn0file0 citeturn2search0

Where NetworkManager profiles are used by the implementation, upstream NetworkManager normally stores keyfile profiles beneath /etc/NetworkManager/system-connections/; those files can contain secrets and are protected so that inappropriate non-root readability/writability causes them to be ignored. Their existence does not supersede AgentOS's host/World authority separation. citeturn5search1turn5search8 fileciteturn0file0

Inbound service exposure is deny-by-default for agents. Publishing a service must result in a capability identifying protocol, address, port, Workspace, lifetime and provenance. fileciteturn0file0

User accounts. Inside a World, ordinary Linux account administration is permitted:

sudo useradd developer
sudo passwd developer
sudo usermod -aG somegroup developer

Those operations affect World identity state, not Control identity. During branch integration, /etc/passwd, /etc/group, /etc/shadow, /etc/gshadow, /etc/subuid, and /etc/subgid are semantic resources under the accounts provider rather than generic text files. If independent branches assign the same numeric UID/GID incompatibly and the provider cannot prove a safe transformation—including associated file ownership, ACLs and group references—the integration must fail instead of guessing. fileciteturn0file0

Desktop hardware access is capability-based. Wayland, X11, PipeWire, camera, microphone, clipboard, notifications, SSH/GPG agents, container-engine sockets, libvirt, system D-Bus, NetworkManager D-Bus, USB, Bluetooth, printers, and GPU devices are all potentially security-relevant host resources. The human desktop may receive carefully mediated resources necessary for ordinary operation, but agent-standard must not receive the host X11 server, raw host /dev, physical NIC control, host Wayland socket, host SSH/GPG sockets, host container-engine sockets, or unrestricted host D-Bus. fileciteturn0file0

The host compositor retains DRM/KMS ownership. Human staging may receive GPU rendering ability when policy permits, while an untrusted agent should normally receive a virtualized graphics path rather than direct physical modesetting authority. fileciteturn0file0

Secrets are never just another branchable home-directory tree. A managed secret lives in a separately encrypted vault and is delivered by identifier, scope, lease and a broker endpoint or injected credential. AgentOS should support adapters for Secret Service, SSH agent, GPG agent, Git/cloud credential helpers, service credentials and agent tool credentials. A feature that has no right to a user's SSH key must not receive an entire snapshot containing that key and merely hide it afterward. fileciteturn0file0 systemd's credential mechanism independently demonstrates that credentials can be supplied transiently to containers, VMs and services instead of being made ordinary persistent filesystem files. citeturn0search2

A typical agent feature should therefore resemble:

feature workspace
├── SYSTEM                    inherited/granted
├── USER/project/foo          granted
├── USER/private-docs         absent
├── ~/.ssh                    absent
├── browser credentials       absent
├── CACHE                     private
├── IDENTITY                  unique
└── managed secrets           leases/broker only

This pattern is directly prescribed by the TRS's least-authority secret model. fileciteturn0file0

A plaintext password, API key or private key that you yourself save into ordinary versioned state is different: historical copies can remain in checkpoints and backups until every retaining object expires. AgentOS explicitly does not promise physical sanitization of plaintext that previously entered Btrfs versioned history. fileciteturn0file0

Agent workflows, checkpoints, integration, promotion, and history

A checkpoint is the exact state boundary from which features, history and governance operate. It records the participating domain snapshots, World manifest digest, ledger position, consistency class, optional base checkpoint, and creation sequencing. fileciteturn0file0

AgentOS defines three checkpoint consistency levels:

A Btrfs snapshot by itself must not be advertised as database-transaction-consistent unless the relevant service/provider successfully quiesced the application. fileciteturn0file0

Checkpoint creation follows this pattern:

A failure before all required domain snapshots exist creates no valid checkpoint; orphaned intermediate snapshots are later reconciled and reclaimed. fileciteturn0file0

The public Control API operation is:

operation: workspace.checkpoint

No final shell grammar is specified. fileciteturn0file0

Starting an agent feature. Conceptually:

operation: workspace.create
requested type: FEATURE
base: staging/main
profile: agent-standard
grants:
  - selected project state
  - brokered network
  - no secrets unless explicitly requested

Again, this is a representation of the normative API and policy fields, not literal shell syntax. The Workspace must exist, have its identity and capabilities established, and possess its filesystem boundary before agent execution begins. fileciteturn0file0

The standard agent VM may receive only its trusted guest boot components, composed feature Workspace, explicit project grants, dedicated virtual NIC, granted broker endpoints, specifically authorized virtual devices, and bounded CPU/memory/I/O/process resources. It must not receive the physical kernel, raw host disks, host /dev, physical NIC control, host D-Bus, host graphical sockets, SSH/GPG agents, host Podman/Docker control socket, or the World storage root. fileciteturn0file0

Submitting an agent's work does not merge it. The feature submits a ChangeSet, which identifies its exact base/head, selected operations and resources, provider changes, dependency closure, exact parent deltas, provenance, external effects and risk assessment. The feature itself never writes directly into staging as its merge mechanism. fileciteturn0file0

operation: feature.submit
source: <feature workspace>

The exact client syntax and interactive selection UX remain unspecified. fileciteturn0file0

AgentOS does not attempt to semantically merge arbitrary Linux state with one universal algorithm. Resource-specific providers own semantic meaning. The required core providers are filesystem, RPM/DNF, systemd, accounts and AgentOS state domains. Later optional providers may cover Flatpak, NetworkManager settings, desktop settings, OCI/container state or application-specific databases. fileciteturn0file0

The conservative defaults are deliberate:

Successfully parsing something as JSON, YAML, TOML, XML, SQLite or another format is not evidence that arbitrary structural merging is safe. A refusal is considered a valid governance outcome. fileciteturn0file0

Integration is side-by-side. AgentOS creates a new candidate from a precise staging checkpoint, applies the ChangeSet/provider closure there, resolves conflicts, validates the candidate and calculates its exact manifest while live staging remains untouched. If staging changes after the candidate's recorded base, compare-and-swap must fail rather than overwrite the newer human work. fileciteturn0file0

Two integration classes exist. Restart-atomic integration is the default for packages, system configuration, service topology, accounts, security policy, large filesystem changes and cross-resource changes. After candidate validation and successful compare-and-swap, old execution stops and staging restarts from the complete new state. Typed-live integration is allowed only when a provider can guarantee safe apply, concurrency, validation and rollback for a narrowly defined resource. fileciteturn0file0

The practical consequence is that a large package or /etc change from an agent may cause your staging Workspace to restart when you integrate it. The predecessor checkpoint remains available for undo. fileciteturn0file0

Integration and promotion are not synonyms. Integration changes your writable staging future. Promotion advances accepted history. You can integrate work, continue using it for some time, and decide later whether to accept all or only selected governed effects. fileciteturn0file0

Suppose staging contains four changes:

accepted C40
    |
    v
staging:
  A
  B
  C
  D

A promotion may deliberately accept only A + C. The result becomes:

accepted:
C41 = C40 + A + C

continuing staging:
C41 + B + D

Unpromoted work is not supposed to disappear. When the accepted candidate's effects exactly match staging, AgentOS may re-anchor staging metadata; when validation transforms those effects or provider semantics require reapplication, it must construct a governed re-anchor candidate. fileciteturn0file0

Promotion itself follows the strongest invariant-preserving path:

The candidate must be immutable before validation attests to its digest; failures before lineage advancement leave the accepted head unchanged; the old accepted commit is preserved through the rollback window; dependencies and provenance follow the selected resources; and the new object must be independently restorable before its predecessor can become eligible for garbage collection. fileciteturn0file0

The corresponding Control API operation is:

operation: lineage.promote

The trusted authorization UI is required for promotion because accepting state is a Control-plane decision that a potentially compromised World desktop cannot safely approve by drawing its own prompt. fileciteturn0file0

Testing does not mutate the candidate. Validation executes from a disposable writable overlay of an already sealed candidate, and the recorded tested digest must match the candidate later accepted. Any useful mutation discovered while running tests becomes another explicit ChangeSet instead of being silently folded into the object that was supposedly tested. fileciteturn0file0

Rollback is append-only governance. If accepted history is:

C1 -> C2 -> C3

and you decide to return to the state represented by C1, accepted rollback creates a new commit:

C1 -> C2 -> C3 -> C4
                   |
                   +-- state equivalent to C1

History therefore records that the machine reached C2 and C3 before returning to an earlier state. AgentOS does not falsify history by moving the lineage pointer backward and pretending intermediate accepted states never happened. fileciteturn0file0

The Control API representation is:

operation: lineage.restore
target accepted state: <historical commit>

A different option is to create a historical fork from an old commit, producing a fresh Workspace identity and quarantine policy rather than altering main. fileciteturn0file0

Staging time travel also preserves displaced futures. Moving staging back to an old checkpoint does not immediately destroy the checkpoints that came afterward. A subsequent write forms another branch, with the displaced future protected according to undo/grace policy. fileciteturn0file0

Historical execution is quarantined because old persistent state can still cause new external effects. AgentOS distinguishes:

Restoring an old filesystem must therefore not automatically reactivate stale cloud credentials, old deployment agents, queued email, message consumers, scheduled payments, timers, synchronization daemons or similar production actors. fileciteturn0file0

AgentOS promises complete restoration of governed persistent state followed by policy-defined runtime reconstruction, not process-memory checkpointing or deterministic recreation of wall-clock, entropy, scheduler, GPU, device, network-connection or remote-service state. Filesystem rollback similarly cannot "undo" a Git push, email, payment, firmware write or cloud mutation that already occurred elsewhere. fileciteturn0file0

Security freshness is independent of functional history. An old World may be perfectly authentic and internally consistent while containing packages with security vulnerabilities discovered later. AgentOS maintains a separate SecurityBaseline and classifies historical state as CURRENT, STALE, or CRITICAL_STALE. A critically stale state defaults to networking off and production secrets off until explicitly activated; restoring the World never rolls the current Control Host security baseline backward. fileciteturn0file0

This is one of the most important mental models for time travel:

"Authentic historical state" != "safe state for today's Internet"

The distinction is a direct security requirement of AgentOS. fileciteturn0file0

Security, backup, recovery, troubleshooting, and emergency operation

The safest default for autonomous code is agent-standard. Use agent-fast only when you are deliberately accepting a shared-host-kernel boundary for a sufficiently trusted/low-risk task. Do not weaken the isolation profile merely to solve a compatibility inconvenience without understanding that the security boundary has changed. fileciteturn0file0

AgentOS's practical security hierarchy is:

Physical firmware / hardware root of trust
              |
              v
UEFI Secure Boot + trusted loader + signed UKI
              |
              v
Control Host kernel and authenticated host image
              |
              v
AgentOS control services / trusted UI
              |
       +------+------+
       |             |
       v             v
human staging     agent-standard
system container  KVM/QEMU VM
       |             |
       +------v------+
              |
       governed World state

The Control Host boot chain is separate from Worlds. A World-installed kernel may exist as an ordinary file and may be tested in a VM, but it cannot obtain the machine's Secure Boot signing authority merely by being promoted. fileciteturn0file0

The default security habits for owners are:

Btrfs scrub is part of scheduled reference maintenance. Upstream Btrfs documentation describes scrub as a checksum-validation pass over filesystem data and metadata; with replicated profiles it can repair certain damaged blocks by using another verified copy. It is not an independent backup and is not equivalent to a general filesystem checker. citeturn4view2

Backup is governance-aware rather than simply cp -a /. A recoverable AgentOS bundle includes accepted lineage references, WorldCommit and WorldManifest objects, state-domain policy, provider/version metadata, ledger roots, compaction attestations, security-baseline data, control-schema version, selected staging/feature checkpoints, backup-set manifest and key identifiers. A restore is complete only after verifying object manifests, ledger anchors, lineage identity, policy, provider metadata and backup authenticity. fileciteturn0file0

The Control API exposes:

operation: backup.create
operation: backup.verify
operation: backup.restore

Their final command-line syntax, destination URI grammar, scheduler configuration and GUI are unspecified in the TRS. fileciteturn0file0

Btrfs send/receive may be used as an efficient transport where exact snapshot ancestry is suitable, but AgentOS does not equate a Btrfs stream with its semantic history model. The backup must carry enough authenticated AgentOS governance metadata to reconstruct lineages and verify what the bytes mean. fileciteturn0file0

Off-machine user data must be encrypted before it leaves the device. Backups must not casually copy the Secure Boot private key, TPM-sealed device-local secrets or device-vault root key as ordinary files; key recovery is an independently governed concern. fileciteturn0file0

Recommended end-user backup workflow:

The TRS requires ongoing backup verification and a disaster-recovery exercise restoring onto a different physical disk where Btrfs filesystem UUIDs, subvolume IDs and inode allocation differ. Logical World identity must survive those physical changes. fileciteturn0file0

Recovery is independent of every World. Destroying World /usr, /etc, /home, packages, desktop configuration or World boot files must not make recovery inaccessible. The recovery environment is part of the trusted Control Host and must be able to list lineages and commits, inspect Workspaces, verify manifests and ledger, inspect storage, launch quarantined historical inspection, restore a lineage, repair staging references, retire broken features, rebuild the control catalog, operate backup restore, inspect Control Host update/fallback, unlock with the recovery key and perform safe garbage collection. fileciteturn0file0

The explicitly named catalog-recovery command is:

agentos recover rebuild-catalog

It reconstructs the control catalog from authenticated historical objects such as WorldCommit descriptors, World manifests, lineage objects, ledger roots, snapshot annotations and backup/recovery metadata. The database is therefore replaceable index state rather than the only interpretation of history. fileciteturn0file0

A disaster-recovery decision flow should look like:

After a bad Control Host update, do not confuse host fallback with World rollback. The Control Host's boot-counted deployment system is independent of World accepted history. If a trial host image repeatedly fails, boot counting should allow the previously working deployment to regain preference; persistent Control Host schema compatibility must be designed so an N−1 host can operate or another rollback-safe migration strategy exists. fileciteturn0file0 systemd's automatic boot assessment explicitly supports marking repeatedly failing entries and blessing successful boots. citeturn0search5

After a failed World integration or promotion, the first principle is: do not repair it by editing accepted objects. Integration is side-by-side and promotion is side-by-side precisely so predecessor state remains intact. A candidate-validation failure should leave live staging untouched; a promotion failure before lineage compare-and-swap should leave the accepted head untouched. fileciteturn0file0

After losing the Control database, use recovery/catalog reconstruction rather than attempting to synthesize history from Btrfs subvolume IDs. World identity is cryptographic and logical; a Btrfs filesystem UUID, subvolume ID, inode number or physical extent is explicitly forbidden as the canonical identity. fileciteturn0file0

After running out of World storage, AgentOS is required to preserve recovery authority. Its response order is deliberately staged: discard ephemeral state, trim safe caches, retire disposable Workspaces, remove already-retired integration objects, explicitly reduce eligible history fidelity, perform authorized compaction, deny new feature creation, rate-limit high-volume history capture, and finally ask the owner for action. The World store must not consume the Control Host's reserved recovery capacity. fileciteturn0file0

The storage-pressure states are NORMAL, PRESSURE, RESTRICTED, and EMERGENCY. A reduction in history fidelity must be recorded; AgentOS may not silently discard history to pretend storage pressure did not occur. fileciteturn0file0

History retention has four advertised fidelity levels:

Dropping from F3 to F2 under emergency pressure is permitted only as an explicit recorded degradation, not as invisible data loss. fileciteturn0file0

Garbage collection is intentionally slow and conservative. Objects pass through LIVE → RETIRED → QUARANTINED → GC_ELIGIBLE → FINAL_REACHABILITY_CHECK → DELETED, with a default grace period before physical deletion. Immediate final deletion requires stronger trusted authorization. Before deletion, reachability must be re-evaluated against every lineage head, staging and feature reference, active candidate, validation object, pin, rollback window, backup, legal hold and recovery dependency. fileciteturn0file0

Common troubleshooting table:

Suggested troubleshooting screenshots for product documentation are a "Workspace versus accepted state" status page, stale-base integration conflict dialog, security-freshness warning for historical state, storage-pressure dashboard showing logical/exclusive/retained/reclaimable estimates separately, Control Host deployment/fallback screen, recovery catalog-verification screen, and backup verification report. These are suggested documentation artifacts derived from information the TRS requires the system to surface; the exact visual design is unspecified. fileciteturn0file0

Administration reference, developer interfaces, performance, compatibility, and explicit assumptions

The following is the consolidated user-facing Control API defined by the TRS. These names are normative operations, not a promise of identical shell command spelling:

Every mutating request must return an operation ID whose state remains queryable after client disconnect or daemon restart. fileciteturn0file0

An implementation should therefore document an operation-state workflow along these lines:

submit mutating operation
        |
        v
receive operation ID
        |
        v
query operation status
        |
   +----+----+
   |         |
 complete   pending/recovering
             |
             v
        query later

The exact status-query method is not named among the minimum API methods, even though queryability is mandatory. That is one of the concrete interface details an implementation manual must add. fileciteturn0file0

Key AgentOS services and their responsibilities:

These privilege separations are part of the AgentOS trusted-computing-base design, not just implementation organization. Each privileged component must have a distinct SELinux domain and only the kernel capabilities, files, sockets, devices and ioctls it needs. fileciteturn0file0

Capability vocabulary. AgentOS defines at least the following capabilities:

WORLD_READ
FEATURE_CREATE
FEATURE_WRITE
FEATURE_REBASE
FEATURE_SUBMIT

STAGING_WRITE
STAGING_INTEGRATE

LINEAGE_PROMOTE
LINEAGE_FORK

HISTORY_PIN
HISTORY_COMPACT
HISTORY_DELETE_FINAL

SECRET_READ
SECRET_DELEGATE

NETWORK_BROKERED_READ
NETWORK_TYPED_EFFECT
NETWORK_RAW

HOST_REBOOT
HOST_DEVICE
HOST_FIRMWARE
HOST_NETWORK_ADMIN

CONTROL_ADMIN
CONTROL_UPDATE
CONTROL_TRUST_ADMIN

A capability must be bound to principal, Workspace, resource scope and, when applicable, a lease. fileciteturn0file0

Policy decisions are deliberately small rather than exposing an arbitrary programmable policy engine in the trusted core: ALLOW, DENY, PROMPT_TRUSTED_UI, or ALLOW_WITH_LIMITS. Rules evaluate principal class, Workspace class, resource class, operation, risk, requested capability and external-effect class. fileciteturn0file0

Conceptual examples from the TRS are:

- principal: agent
  workspace: feature
  operation: network.raw
  decision: deny

- principal: owner
  workspace: staging
  operation: package.install
  decision: allow

- principal: agent
  workspace: feature
  operation: secret.read
  decision: prompt

These illustrate policy semantics; the exact policy-file path and user-facing editing mechanism are not specified. fileciteturn0file0

Developers inside a World should expect conventional Fedora workflows: DNF/RPM, systemd services, Wayland desktop applications, PipeWire, browsers, IDEs, Git, explicit SSH credentials, build toolchains, rootless Podman, nested user namespaces where supported, local databases and mediated USB/device workflows. fileciteturn0file0

Examples remain familiar:

# Development package installation in staging
sudo dnf install gcc make git

# Clone and build a project
git clone <repository>
cd <repository>
make

# Run an ordinary user container, where supported
podman run --rm <image>

# Inspect a World-local service log
journalctl -u my-development-service.service -f

These are Fedora/Unix development operations taking place inside the World boundary; possession of development tools or container root inside a World does not imply Control Host authority. fileciteturn0file0

AgentOS developer/API architecture uses a versioned typed local API. Internal privileged helper IPC is specified as local Unix-domain SOCK_SEQPACKET communication with peer-credential verification, SELinux peer labels, deterministic bounded encoding, explicit protocol versions and descriptor passing through SCM_RIGHTS. Helpers must validate semantic authorization as well as socket peer identity. fileciteturn0file0

Provider developers implement semantics resembling:

StateProvider {
    identify(resources)
    observe(operation)
    diff(base, target)
    dependencies(change)
    merge(base, ours, theirs)
    validate(candidate)
    quiesce(workspace)
    classify_risk(change)
    describe(change)
}

Providers must declare their ID, protocol and implementation versions, owned resource types/schema versions, exact/semantic replay guarantees, merge guarantees, required authority, required networking and maximum execution class. Provider code runs outside agentosd; candidate hooks must never be executed as arbitrary Control Host root. fileciteturn0file0

The reference implementation expects new privileged AgentOS components to be written primarily in Rust; Python and shell are intended mainly for build tooling, tests, fault injection, image generation and development utilities rather than primary authorization, persistent-object parsing or broker logic. fileciteturn0file0

Customization boundaries. Inside staging, normal Linux customization is a product objective: packages, development stacks, World /etc, local users, World services, user configuration, applications, rootless containers and desktop state are all intended to be modifiable. fileciteturn0file0

Control Host customization is deliberately different. The host is image-based and signed, with authenticated read-only content emphasized and persistent executable/configuration state minimized. Users should therefore not treat the Control Host like a conventional mutable Fedora root and manually install arbitrary host RPMs to fix a World problem. Changes requiring new host code or capabilities belong in an authenticated Control Host release or explicitly governed Control extension, not ordinary World history. fileciteturn0file0

Performance tuning. The specification sets release targets rather than a large collection of end-user tuning knobs:

If a hard checkpoint would freeze an interactive desktop beyond the configured threshold, the TRS prefers aborting or falling back to a lower consistency level over freezing the desktop indefinitely. fileciteturn0file0

For users, the resulting tuning guidance is conservative. Avoid routine defragmentation of versioned history; do not enable NODATACOW on ordinary versioned state; allow scheduled scrubs and integrity verification to run; monitor storage-pressure indicators rather than judging history usage only from ordinary logical file size; retire disposable Workspaces that are no longer required; and avoid weakening agent-standard isolation solely for small performance gains unless the risk is explicitly acceptable. These recommendations follow directly from the TRS's Btrfs, storage-pressure and execution-profile requirements. fileciteturn0file0

Btrfs's current scrub documentation says a full-filesystem scrub can validate checksummed data and metadata and recommends periodic execution; the AgentOS TRS itself requires scheduled scrub while leaving the exact scheduler configuration to the implementation. citeturn4view2 fileciteturn0file0

The UI must not present one misleading "branch size" number because copy-on-write history shares extents. AgentOS distinguishes logical size, exclusive physical size, estimated retained size, estimated reclaimable size and hard budget/quota. Estimates must be labeled as estimates. fileciteturn0file0

Compatibility targets. The intended human environment includes ordinary Fedora developer workflows and requires desktop qualification for the following categories:

These are architectural release gates, not optional polish. A compatibility fix that requires giving human staging physical-host root authority is considered an architecture failure by the TRS. fileciteturn0file0

The reference human container combines systemd-nspawn, private user namespaces, non-overlapping UID/GID allocation, idmapped mounts, private mount/PID/IPC/UTS namespaces, cgroup v2, SELinux MCS separation, seccomp, Landlock where useful, restricted devices/sockets/D-Bus and virtualized networking. systemd-nspawn itself supports private user namespaces, private networking, virtual Ethernet links, capability restriction and syscall filters among its container configuration mechanisms. fileciteturn0file0 citeturn3search0

Architecture diagram recommended for the end-user "About AgentOS" screen:

The architecture reflects the TRS's core division: the Control Host owns the machine; Worlds own ordinary durable computing state; Workspaces own mutable futures; providers own semantic knowledge; AgentOS owns governance. fileciteturn0file0

Complete assumptions and unspecified implementation details. These are important because producing an end-user handbook from an architecture TRS necessarily exposes places where the specification intentionally defines behavior but not final product UX:

Representative end-to-end workflow: ordinary human development.

# Work normally in persistent staging.
cd ~/src/project
git pull

# Install a development dependency.
sudo dnf install clang

# Edit, build and test.
$EDITOR src/example.c
make
make test

No explicit AgentOS transaction is required first. The files, package changes and ordinary World configuration remain in persistent staging across restarts. Later, the owner can create a checkpoint or select state for promotion into accepted history. fileciteturn0file0

Representative end-to-end workflow: delegate a task to an untrusted agent.

staging/main
    |
    | exact checkpoint
    v
feature workspace
profile: agent-standard
grants:
  project repository only
  brokered read networking
  no production secrets
    |
    | agent modifies/tests
    v
feature.submit
    |
    v
side-by-side integration candidate
    |
    | provider validation + optimistic CAS
    v
staging/main

The agent can be root inside the VM if the use case requires it while remaining unable, by that fact alone, to modify the physical host, accepted lineage, staging Workspace, Control authorization, host boot trust or ungranted secrets. fileciteturn0file0

Representative end-to-end workflow: safely accept a package change produced by an agent.

The agent installs or removes RPMs in its feature. The RPM provider records the exact package transaction and repository evidence. Submission does not change staging. Integration constructs a candidate, expands dependencies where necessary, executes package scriptlets only in the candidate environment, validates it and then uses restart-atomic integration if accepted into staging. Later promotion constructs another immutable accepted candidate, tests its exact digest, seals the new WorldCommit and advances main with compare-and-swap. At no stage does an agent package script run as Control Host root. fileciteturn0file0

Representative workflow: investigate an old configuration without waking dangerous services.

operation: history.inspect
target: <historical checkpoint>
mode: HISTORICAL_INSPECTION

AgentOS should realize it read-only or behind a disposable overlay, normally without networking or secrets. The user can inspect files and configuration without silently restarting an old synchronization agent, CI runner, deployment worker, mail queue or scheduled effect with production authority. fileciteturn0file0

Representative workflow: recover after catastrophic World corruption.

Boot the independent Control Host recovery environment; unlock with the recovery key if TPM-based unlock is unavailable; verify storage, object manifests and ledger commitments; inspect accepted lineages and checkpoints; rebuild the control catalog if the SQLite index is lost; select the desired authenticated accepted World or backup set; restore it; verify provider/policy metadata; and only then reconstruct normal runtime according to current policy. Destroyed World /usr, /etc, /home or desktop state must not prevent this recovery path. fileciteturn0file0

The result of this architecture is an operating model in which ordinary Linux usability and strong agent isolation coexist without treating every user action as a transaction. The human receives a persistent, writable Fedora workstation. Agents receive powerful but independently writable futures. The Control Host alone retains physical authority. Accepted state advances through explicit, sealed, validated history. Failed integrations and failed promotions preserve predecessors. Recovery remains independent from World damage. Remote and physical effects are never falsely claimed to have been undone by local rollback. Those properties—not a particular GUI shell or command spelling—are the core user contract established by the August 24, 2026 AgentOS TRS. fileciteturn0file0