Documentation

Operator handbook

Practical docs for daily FoundryOS use — getting started, the first-party apps, real commands from the shipped image, and what to do when something breaks.

Getting started

FoundryOS is a Debian 13 desktop with a frozen, snapshotted base and fresh tooling in layers above it. Boot-level rollback means a bad change is recoverable from the bootloader — not a reinstall. Read Why for the reasoning; this page is how you operate it.

1. Install and first boot

Grab the image from Download. The installer sets up LUKS2, Btrfs with snapper, and Secure Boot out of the box. On first login, Welcome runs once — suggested Flatpaks, optional self-heal and AI toggles, smartcard setup pointers.

welcome-assistant          # re-open first-run
cat /usr/lib/foundryos/build-info   # build identity

2. Know your control surfaces

Day-to-day work lives in first-party apps — not scattered terminal incantations. Each apppresents state and delegates privileged work to pkexec-gated helpers. Foundry Control is the hub; specialized assistants handle updates, snapshots, health, freshness, and crucibles.

foundry-control — settings hub
updates-assistant — apt + Flatpak updates
snapshot-assistant — create / restore / annotate snapshots
health-assistant — diagnostics and bundles
freshness-assistant — curated backports catalog
crucibles-assistant — sealed Podman workspaces

3. Where apps come from

Order of preference on FoundryOS:

Flatpak (Flathub) — browsers, IDEs, most desktop apps. Sandboxed, current.
Freshness catalog — verified backports bundles (`foundryos-freshness catalog list`).
Crucibles — try/build software in a sealed container (`foundry-crucible`).
apt on the base — possible but guarded; snapshots precede mutations. Prefer layers above for freshness.

Daily use

Updates

Open Updates, or check from a terminal:

foundryos-update --check --format json
pkexec foundryos-update --apply --yes

Security-only auto-apply is Debian-Security origin only. Reboot when Updates says so.

Snapshots & rollback

Every apt transaction gets a pre-snapshot. Restore from Snapshots or CLI:

foundryos-rollback --list
foundryos-rollback 42 --yes
sudo reboot

Boot menu entries from grub-btrfs let you preview before promoting.

Fresh packages

Standard tier = verified catalog. Advanced = opt-in backports search:

foundryos-freshness catalog list
sudo foundryos-freshness install --catalog TOOLCHAIN

Crucibles

Sealed workspaces — no host file access unless you opt in:

foundry-crucible catalog list
foundry-crucible create --catalog debian-trixie --name dev
foundry-crucible enter dev

When something feels wrong

Health runs a deterministic rules engine — no network, no model unless you opted in:

foundryos-diagnose --format text
foundryos-journal list
foundryos-bundle --tier 0 --output ~/foundryos-bundle.json

Findings often suggest foundryos-rollback — same primitive Snapshots uses.

First-party assistants

GTK apps shipped in the image. GUI is the default; headless flags exist for scripting and tests.

Foundry Control

/etc/foundry-control/config.ini

Settings hub for recovery, security, software freshness, AI assistant, smartcard, domains, and graphics.

Launch: foundry-control

Command	Description
foundry-control	Open the settings hub (GTK).
foundry-control --version	Print version and exit.

Welcome

/etc/welcome-assistant/config.ini

First-run onboarding: suggested Flatpaks, opt-in toggles, and completion marker.

Launch: welcome-assistant

Command	Description
welcome-assistant	Open Welcome (or autostart on first login).
welcome-assistant --version	Print version.
welcome-assistant --print-install-cmd APP_ID	Print the flatpak install argv for a suggested app id.
welcome-assistant --mark-completed [--skipped]	Mark first-run complete (headless/tests).
welcome-assistant --force	Show Welcome even if already completed.
welcome-assistant --autostart	Autostart entry mode (skips live session / completed).

Updates

/etc/updates-assistant/config.ini

Presents pending apt/Flatpak updates; all apply paths delegate to foundryos-update via pkexec.

Launch: updates-assistant

Command	Description
updates-assistant	Open Updates.
updates-assistant --version	Print version.
updates-assistant --print-check-cmd	Print the check argv (default: foundryos-update --check --format json).
updates-assistant --selftest	Headless parser/argv self-check.

Snapshots

/etc/snapshot-assistant/config.ini

List, create, restore, and annotate Btrfs snapshots. Restore delegates to foundryos-rollback.

Launch: snapshot-assistant

Command	Description
snapshot-assistant	Open Snapshots.
snapshot-assistant --version	Print version.
snapshot-assistant --print-restore-cmd ID	Print pkexec foundryos-rollback ID --yes from config.
snapshot-assistant --summarize-changes	Read journal JSON from stdin; print one-line change summaries.
snapshot-assistant --format-change-detail	Read journal JSON from stdin; print detail lines.

Health

/etc/health-assistant/config.ini

Read-only diagnostics UI: rule-based findings, change journal, bundles, optional AI reasoner.

Launch: health-assistant

Command	Description
health-assistant	Open Health.
health-assistant --version	Print version.
health-assistant --print-diagnose-cmd	Print foundryos-diagnose argv from config.
health-assistant --backend	Print resolved [assistant] backend (none/local/lan/frontier).
health-assistant --invoke-reasoner	Run foundryos-reasoner; print JSON to stdout.
health-assistant --selftest	Headless parser/verdict self-check (reads diagnose JSON from stdin).

Freshness

/etc/freshness-assistant/config.ini

Curated backports catalog (Standard) and opt-in Advanced unrestricted installs.

Launch: freshness-assistant

Command	Description
freshness-assistant	Open Freshness.
freshness-assistant --version	Print version.
freshness-assistant --print-install-cmd CATALOG_ID	Print pkexec foundryos-freshness install --catalog … argv.
freshness-assistant --print-unrestricted-install-cmd PKG	Print Advanced unrestricted install argv.

Crucibles

— (uses foundry-crucible)

GUI for sealed Podman workspaces: catalog browse, create, enter, import/export.

Launch: crucibles-assistant

Command	Description
crucibles-assistant	Open Crucibles.
crucibles-assistant --version	Print version.

CLI tools

One section per tool, commands as rows. Privileged commands expect pkexec or sudo as shipped.

Updates & system

foundryos-update

foundryos-update --check [--format json\|text]	List pending upgrades (read-only).
foundryos-update --refresh	Refresh apt metadata (pkexec from Updates app).
foundryos-update --apply [--yes]	Apply pending upgrades (snapshot-first).
foundryos-update --apply-offline [--yes]	Offline PackageKit apply path.
foundryos-update --status [--format json\|text]	Last apply/check summary.
foundryos-update --selftest	Parser self-check.

foundryos-rollback

foundryos-rollback SNAPSHOT_ID [--dry-run] [--yes]	Make a snapper snapshot the live @ root; reboot to finish.
foundryos-rollback --promote-current [--dry-run] [--yes]	When booted into a grub-btrfs preview, promote that snapshot.
foundryos-rollback --list	Show available snapper snapshots.
foundryos-rollback --list-backups	Show previous roots kept aside (@.rollback-*).
foundryos-rollback --prune-backups [--yes]	Delete all kept-aside previous roots.

foundryos-self-heal

foundryos-self-heal status [--json]	Boot counter, tripwire, last-known-good snapshot.
foundryos-self-heal config [--json]	Resolved self-heal.conf.
foundryos-self-heal mark-attempt	Increment boot-attempt counter (boot hook).
foundryos-self-heal mark-healthy [N]	Reset counter; record snapshot N as last-good.
foundryos-self-heal heal [--yes]	Recovery: roll back to recorded last-good.
foundryos-self-heal --selftest	Pure-logic self-check.

foundryos-self-heal-setup

foundryos-self-heal-setup enable \| disable	Opt in/out of auto-rollback (pkexec; writes self-heal.conf).
foundryos-self-heal-setup set-threshold N	Unhealthy boots before tripwire (N ≥ 1).
foundryos-self-heal-setup set-auto-promote yes \| no	Auto-promote preview boots to @.

Freshness (Layer 2)

foundryos-freshness

foundryos-freshness catalog list [--json]	List verified catalog offers.
foundryos-freshness catalog show ID	Show one catalog entry.
foundryos-freshness catalog lint	Offline catalog validation (build gate).
foundryos-freshness install --catalog ID	Install a verified offer (root; apt hook snapshots).
foundryos-freshness verify --catalog ID	Dry-run prove offer resolves (no changes).
foundryos-freshness search QUERY	Discover backports packages (Advanced).
foundryos-freshness install --unrestricted PKG …	Install from backports (Advanced; consent required).
foundryos-freshness status	Pins and install log.
foundryos-freshness pin add PKG	Pin package to trixie-backports (root).

Crucibles

foundry-crucible

foundry-crucible catalog list [--json] [--category base\|ai-dev]	List verified workspace templates.
foundry-crucible catalog show ID	Show one catalog entry (JSON).
foundry-crucible catalog lint	Offline catalog validation.
foundry-crucible create --catalog ID --name NAME [--gpu] [--share DIR …] [--share-ro DIR …] [--dry-run]	Create a sealed/shared workspace.
foundry-crucible create --file FILE.crucible [--dry-run] [--i-understand-unverified]	Create from a Crucible file.
foundry-crucible list [--json]	List local Crucibles (state, size, drift).
foundry-crucible enter NAME	Start container and open an interactive shell.
foundry-crucible start NAME \| stop NAME	Lifecycle without a shell.
foundry-crucible recreate NAME	Rebuild from live catalog; keep private data.
foundry-crucible run NAME [--detach\|-d] [-- EXTRA]	Run verified catalog launch command.
foundry-crucible launch-hint NAME [--json]	Print catalog launch command and URL.
foundry-crucible gpu-detect [--json]	Report GPU vendor available for --gpu.
foundry-crucible remove NAME [--purge]	Remove workspace and launcher.
foundry-crucible export NAME [-o FILE.crucible] [--config]	Export .crucible object or YAML config.
foundry-crucible pack NAME [-o FILE.run] [--dry-run]	Build self-running .crucible.run pack.
foundry-crucible import FILE.crucible [--dry-run] [--i-understand-unverified]	Import object or YAML Crucible.
foundry-crucible verify FILE.crucible	Report verified vs unverified.
foundry-crucible sign OBJECT [--key KEY] [-o FILE.sig] [--dry-run]	Detached GPG provenance signature.
foundry-crucible verify-sig OBJECT [SIG] [--dry-run]	Verify detached provenance.
foundry-crucible app NAME	Launch declared in-container app.
foundry-crucible app-set NAME --title T --exec CMD [--gui] [--icon FILE.png]	Declare app for next export.

Diagnostics

foundryos-diagnose

foundryos-diagnose [--format text|json] [--output FILE]

Rule-based findings from change journal + boot health.

foundryos-bundle

foundryos-bundle [--tier 0\|1\|2] [--backend none\|local\|lan\|frontier] [--output FILE]	Redacted diagnostic bundle (disclosure tier explicit).
foundryos-bundle --extra FILE …	Attach scrubbed text (tier ≥ 1).
foundryos-bundle --raw FILE …	Attach raw files (tier 2, on-device only).
foundryos-bundle --force	Permit tier 2 to LAN backend.
foundryos-bundle --allow-frontier-full	Permit tier 2 to frontier backend.

foundryos-journal

foundryos-journal list	List change-record ids (newest first).
foundryos-journal show ID	Print change record + fingerprint.
foundryos-journal find --snapshot N [--format ids\|json]	Find records linked to snapshot N.
foundryos-journal current-snapshot [--format value\|json]	Current snapper snapshot number.
foundryos-journal state --snapshot N [--format text\|json]	Derived state of one snapshot.
foundryos-journal states [--format text\|json]	Derived state of every known snapshot.
foundryos-journal diff A B [--format text\|json]	Structured diff between snapshots.
foundryos-journal fingerprint --snapshot-id N	Capture fingerprint artifact.
foundryos-journal record-change --trigger …	Write change record (hook/internal).
foundryos-journal validate FILE	Validate JSON artifact schema.

foundryos-reasoner

foundryos-reasoner [--format json] [--tier 0\|1\|2] [--backend …] [--dry-run]	Optional AI reasoner over a bundle (off by default).
foundryos-reasoner --base-url URL --model M [--force]	Override endpoint/model.

foundryos-assistant-setup

foundryos-assistant-setup status [--json]	Read [assistant] backend and reachability.
foundryos-assistant-setup set --backend none	Disable AI reasoner (pkexec).
foundryos-assistant-setup set --backend local [--base-url URL] [--model M]	On-device backend (pkexec).
foundryos-assistant-setup set --backend lan --base-url URL --model M	LAN backend (pkexec).
foundryos-assistant-setup set [--base-url URL] [--model M]	Edit current backend endpoint.

Security & enterprise

foundryos-smartcard

foundryos-smartcard status [--json]	PKCS#11 module, reader/card, per-browser registration.
foundryos-smartcard enable [TARGET] [--json]	Register OpenSC (native) or p11-kit proxy (Flatpak).
foundryos-smartcard disable [TARGET] [--json]	Unregister module.
foundryos-smartcard refresh [--json]	Re-sync staged p11-kit clients after host upgrade.

foundryos-trust

foundryos-trust inspect FILE … [--json]	Parse certs; show subject/fingerprint.
foundryos-trust import FILE … [--yes] [--json]	Import CA into system store + all browser NSS DBs.
foundryos-trust import … --browsers-only \| --system-only	Import to one leg only.
foundryos-trust list [--json]	Anchors previously imported by this tool.
foundryos-trust remove FINGERPRINT_PREFIX [--yes]	Remove anchor everywhere.

foundryos-tpm-enroll

foundryos-tpm-enroll --status	TPM2 / LUKS / enrollment state (JSON).
foundryos-tpm-enroll --enroll [--pcrs 7] [--force] [--passphrase-file PATH]	Add TPM2 keyslot (pkexec; passphrase required).
foundryos-tpm-enroll --unenroll [--passphrase-file PATH]	Remove TPM2 keyslot (pkexec).

foundryos-ad-verify

foundryos-ad-verify preflight DOMAIN	DNS SRV checks before realm join.
foundryos-ad-verify verify [--domain DOMAIN]	Post-join health check.
foundryos-ad-verify verify --repair [--dry-run] [--domain DOMAIN]	Apply SRV-derived ad_server fix when needed.

foundryos-domains-apply

foundryos-domains-apply join DOMAIN USER	Snapshot + realm join (stdin: password; pkexec).
foundryos-domains-apply leave DOMAIN	realm leave (pkexec).

foundryos-nvidia-setup

foundryos-nvidia-setup status [--json]	GPU, driver, Secure Boot, MOK state.
foundryos-nvidia-setup enable	Install + sign DKMS module (pkexec).
foundryos-nvidia-setup disable	Purge NVIDIA packages (pkexec).
foundryos-nvidia-setup selftest	Pure-logic self-check.

Snapshot helpers (privileged)

foundryos-snapshot-list

foundryos-snapshot-list CONFIG [json|table]

Privileged snapper list (auth_admin_keep).

foundryos-snapshot-metadata

foundryos-snapshot-metadata CONFIG ID USERDATA

Privileged snapper modify --userdata (notes/pin).

Config paths

Files the helpers and assistants read. Override paths via documented env vars where noted.

Path	Purpose
/etc/foundryos/diagnostics.conf	Diagnostics data dir, snapper config, [assistant] AI backend.
/var/lib/foundryos/diagnostics/	Change records, fingerprints, boot health artifacts.
/etc/foundryos/self-heal.conf	Self-heal enabled, threshold, auto_promote.
/etc/foundry-control/config.ini	Helper command paths for Foundry Control pages.
/etc/health-assistant/config.ini	Diagnose, journal, bundle, reasoner command paths.
/etc/snapshot-assistant/config.ini	Restore command and snapper config name.
/etc/updates-assistant/config.ini	foundryos-update command path.
/etc/freshness-assistant/config.ini	foundryos-freshness command path.
/usr/share/foundryos/freshness/catalog.json	Verified Freshness catalog.
/usr/share/foundryos/crucibles/catalog.json	Verified Crucibles catalog.
~/.local/share/foundryos/crucibles/	Local Crucible state (override: FOUNDRY_CRUCIBLE_HOME).
/usr/local/share/ca-certificates/foundryos-trust/	System CA anchors imported by foundryos-trust.
/usr/lib/foundryos/build-info	Build commit stamped at image build (include in bug reports).

Troubleshooting & FAQ

How do I check what's wrong after a bad update?+

Start with Health or run foundryos-diagnose --format text. It ranks suspect changes and prints reversible fix commands — usually a snapshot rollback.

How do I roll back without the GUI?+

foundryos-rollback --list, then foundryos-rollback SNAPSHOT_ID (confirm), reboot. From the grub-btrfs menu you can boot a preview read-only, then foundryos-rollback --promote-current.

Security updates applied without asking — is that normal?+

Yes. Only Debian-Security origin packages auto-apply, and they still go through the snapshot-first apt hook. Everything else asks in Updates.

Smartcard works in native Firefox but not Flatpak Firefox?+

Run foundryos-smartcard status --json. Flatpak browsers need the p11-kit bridge: foundryos-smartcard enable flatpak-firefox. After a host p11-kit upgrade, foundryos-smartcard refresh.

Agency CA for CAC/PIV web sign-in?+

foundryos-trust inspect bundle.p7b, then foundryos-trust import bundle.p7b. Imports system trust store and every detected browser NSS profile.

What goes in a bug report?+

See Report a bug: cat /usr/lib/foundryos/build-info, foundryos-diagnose --format text, foundryos-bundle --tier 1 --output ~/foundryos-bundle.json, email bugs@foundrylinux.com.

Self-heal (opt-in)

When enabled in Foundry Control → Recovery, consecutive unhealthy boots trigger automatic rollback to the last-known-good snapshot. Inspect state:

foundryos-self-heal status --json
pkexec foundryos-self-heal-setup enable

Operator handbook

On this page

Getting started

1. Install and first boot

2. Know your control surfaces

3. Where apps come from

Daily use

Updates

Snapshots & rollback

Fresh packages

Crucibles

When something feels wrong

First-party assistants

Foundry Control

Welcome

Updates

Snapshots

Health

Freshness

Crucibles

CLI tools

Updates & system

foundryos-update

foundryos-rollback

foundryos-self-heal

foundryos-self-heal-setup

Freshness (Layer 2)

foundryos-freshness

Crucibles

foundry-crucible

Diagnostics

foundryos-diagnose

foundryos-bundle

foundryos-journal

foundryos-reasoner

foundryos-assistant-setup

Security & enterprise

foundryos-smartcard

foundryos-trust

foundryos-tpm-enroll

foundryos-ad-verify

foundryos-domains-apply

foundryos-nvidia-setup

Snapshot helpers (privileged)

foundryos-snapshot-list

foundryos-snapshot-metadata

Config paths

Troubleshooting & FAQ

Self-heal (opt-in)

Related pages

Download

Security

Decisions

Report a bug

Documentation index