SodaOS — An Open-Source Operating System for AI Software Factories

Mandatory policy: Freshness takes priority over reproducibility. AI provider CLIs must track current upstream releases; all managed dependencies and every new baseline must follow the same freshness rule.

SodaOS is a self-hosted operating system appliance built on Fedora CoreOS. It integrates persistent Podman project environments, Forgejo collaboration, AI agent coordination and policy-governed verification and merge, so teams can operate a software factory without assembling that infrastructure themselves.

Start with the AI software factory OS overview, technical reference and infrastructure comparisons.

A person authorizes factory operation in Forgejo. Soda coordinates eligible issues through bounded agent execution in a persistent Project, pull requests, CI and independent review of the exact candidate commit. Corrections receive fresh verification; merges require the configured policy and current native authority. Every run has a recorded outcome and separately tracked cleanup. The product overview owns the complete lifecycle.

Persistent shared Projects support human development, debugging and intervention through native Forgejo, SSH, Git, mise and container tools. Developers do not receive individual Linux accounts on the host.

Soda integrates Forgejo's native frontend and authentication with Spaces, a protected Go environment/access API, native provisioning, Tailnet operator settings and stock branded Cockpit. The dashboard backend owns factory coordination and its PostgreSQL ledger; soda-factory exposes private operator status, stop and reconciliation commands.

Start with the Factory journey. The operator reference describes configuration and commands; manual development is a separate path.

Documentation index: docs/README.md.

Choose the installer and deployment path, follow installation, and consult the selected release's notes and assets. Docker is a separate runtime path with its own release and host requirements.

Projects share the host Linux kernel; they are not hardware-isolated VMs or a hostile multi-tenant sandbox. The Docker runtime is privileged and trusts its dedicated host operator. Self-hosted coordination can use external coding providers and TypeSafe/JEV; it does not imply offline AI. See the trust model.

CanLang is an optional, independently usable language for custom business applications. SodaOS coordinates development; CanLang supplies application constructs. Projects can use other languages too.

System

Fedora CoreOS host — operator administration only
├── Stock branded Cockpit, tailscaled and trusted project Tailnet companions
├── soda-host — privileged Project, terminal and Tailnet operations
├── soda-identity — private provider-credential broker
├── soda-factory — client for the backend's private operator interface
└── Podman
    ├── Fountain / Forgejo — native frontend, identity/Git and extension host
    ├── Soda Go service — environment API and factory coordinator
    ├── PostgreSQL — separate Soda and Forgejo databases
    ├── Caddy — configured private HTTPS endpoints
    └── Persistent Project OS containers
        ├── Separate human and factory accounts and checkouts
        ├── Supervised human terminals and factory agent runs
        ├── Actual shared installed tools/files
        └── Native nested workloads and persistent service data

Forgejo, Soda and Caddy are separate containers; Forgejo is not a Podman pod. See architecture and system/host/services/ for ownership and placement. The repository's human owner administers its project, not the host. Each user explicitly joins. Native Git authorization is separate. Normal startup preserves the existing container/root; see Project OS.

Project access is ordinary user@project-ip, SCP/SFTP and native service ports. Clients need a real route; host Tailnet enrollment alone does not provide it. Cockpit listens on all interfaces/root-only. Browser origins, Git advertisement and project routing are separate configuration.

Source and guides

Area	Source / documentation
Product and architecture	Overview, Architecture, Scope
Bounded software work	Factory command, internal/factory/, Operator reference, Factory journey
Host capability strategy	Host strategy
API / auth / Forgejo customization	cmd/, internal/, API, Credentials, Forgejo
Installation / operator access	system/, scripts/, Installation, Operator setup, Media

Supported platform scope belongs to Release architecture. Build and test within the current task. Installation, provider mutations and destructive cleanup follow the user’s existing authorization. Preserve credentials, project state, backups and failed evidence.

Rust package guides

Every Cargo package has a local guide to its purpose, prerequisites and use. Start with the installed commands for appliance or project work. Library guides are for Rust consumers; build and fixture tools are for release developers and operators. Run their Cargo examples from this repository's root with the toolchain selected by rust-toolchain.toml.

Package guide	Use
Activation	Activate private browser and Git access.
Console welcome	Read appliance network and access guidance.
Factory command	Inspect and retire supervised factory runs.
Forgejo domain	Control the Forgejo writer domain during recovery.
Forgejo migration	Prepare database-password configuration at startup.
Identity Compose	Give a selected nested service Muse access.
Identity broker	Operate the private provider-credential broker.
Image import	Import bundled images into host Podman storage.
Installer	Install to disk and continue appliance setup.
Muse launcher	Run Muse from a provisioned project account.
Project maintenance

Go package guides

Command guides describe installed or development-tool use. Internal package guides explain their user-facing feature and the integration surface for Go consumers in this module. The test packages document focused checks and their prerequisites. Toolchain and dependency pins, including the local Forgejo SDK replacement, live in go.mod.

Package guide	Use
Dashboard	Operate the Soda backend and factory coordinator.
Forgejo extension	Run the native Forgejo extension bridge.
Tailnet command	Inspect Tailnet status and operator guidance.
Installed acceptance	Invoke scoped native client probes.
Avatar renderer	Render deterministic robot SVGs.
Configuration	Load and validate dashboard/operator configuration.
Factory records	Use canonical factory records and validation.
Factory coordinator	Coordinate readiness, dispatch and supervised run lifecycles.
File locks	Hold advisory locks around cooperating processes.
Forgejo client	Observe and act through native Forgejo APIs.
Factory publication

License

Original SodaOS code, documentation and configuration are licensed under Apache-2.0. NOTICE defines attribution and scope. This does not relicense inherited code, canonical artwork or third-party material; their existing terms apply, and a missing inherited license is not an Apache grant.

Preserve Forgejo and other dependency licenses. Actual-artifact corresponding-source, notice/font delivery and inherited-rights clearance remain required under licensing, not satisfied by adding the original-code license.