SodaOS combines a Fedora CoreOS host with persistent Podman Projects, Forgejo collaboration and agent coordination. It uses the host's Linux kernel; it does not introduce a separate kernel or hardware-isolated execution layer.
Software work and execution
| Concept | Meaning |
|---|---|
| Run | One bounded supervised agent execution with a recorded identity, exact process binding and outcome |
| Persistent Project | A shared repository environment for humans and factory roles, with lasting tools/services and separate accounts/checkouts |
| Attempt | A bounded effort against accepted requirements and recorded repository inputs |
| Work item | An issue whose objective, dependencies and required outcomes drive factory work |
Forgejo owns software collaboration and repository policy; Soda owns supervised coordination, execution and its records; the agent performs the task. Authorized, ready work advances through coding, candidate publication, review, correction, required checks and native merge under repository policy. Material questions and unresolved dependencies block affected work. Human approval is required where policy calls for it; it is not a mandatory final step for every routine change.
Runs end when work finishes, limits expire or the operator stops them. Their settlement is recorded separately from their outcome. Follow the factory walkthrough.
Identities for factory work
| Identity | Role |
|---|---|
| Soda execution principal | Identifies a single run and its permitted operations |
| Provider account | Supplies model access under its own authentication and usage terms |
A role is an authority template, not permission for an agent to name itself a reviewer or grant another process additional access. Separate identities constrain operations; they do not guarantee independent reasoning or correct code.
Factory runs execute inside Projects with host-enforced boundaries but share the host kernel. Soda is for a trusted team on a private network, not hostile public multitenancy. Provider credentials require protected enrollment and may require renewal; credential return cannot revoke a token copied outside the runtime.
Persistent development environments
Projects have separate roots and persistent state. Within each Project, humans and authorized factory roles have distinct accounts and executions while sharing tools and services. The following layers describe manual development and intervention.
Three layers for human development
| Layer | What lives there |
|---|---|
| Appliance | Compute, storage, private networking, Soda dashboard, Forgejo and operator services |
| Project environment | Persistent Rocky Linux userspace, its own IP, shared installed tools, shared files and project services |
| Your workspace in that project | Your Linux account, home, ordinary Git checkouts, personal configuration, credentials and processes |
One repository has one associated environment. A workspace is your place inside that shared environment, not another VM or a container created for every person. You join only the projects you need. The same person can have an account in several independent environments without having any Linux account on the host.
A saved factory request is none of these: it is your private shaping draft (objective, ideas, review) kept before any issue or Project exists. See the factory walkthrough for the everyday journey from request to repository work.
Tools installed in the shared project toolchain are actual shared installations, not merely a shared download cache. Personal checkouts are not a shared writable working tree: collaborate with branches, commits and reviews. Shared files and services are deliberately shared; coordinate changes with teammates.
Identities and authority
| Identity or role | Authority |
|---|---|
| Forgejo account | Your browser identity and upstream repository permissions |
| Project member | Your project-local files, processes, shared resources and SSH access |
| Associated repository's human owner | Administration inside that project, including shared tools and its container engine |
| Configured Soda operator | Soda environment/access administration and initial team onboarding |
| Forgejo site administrator | Forgejo administration, under Forgejo's own permissions |
| Native host root/operator | Host services, storage, networking and Cockpit |
Owning a repository or administering Forgejo does not grant host root. A project administrator's sudo access stays inside that project. Organizations and teams can organize repository collaboration; they do not automatically create an organization-owned Linux environment or map team roles to project sudo.
Soda is for a trusted team on a private network. Project namespaces and account permissions reduce accidental interference; they are not a hostile-multitenancy security guarantee. Do not give untrusted contributors project administration or local runner execution merely because their work is in a container.
Four separate kinds of access
- Browser: Forgejo authenticates you; Soda has its own session for its dashboard.
- Project SSH: your client proves possession of a private key whose public half Soda installs when you explicitly join.
- Git: Forgejo or another Git host authorizes your own Git key or HTTPS credential.
- Network: your LAN/Tailnet route and its access rules make an endpoint reachable.
Joining an environment does not grant repository permissions. Browser sign-in does not authenticate a CLI or create a Git key. Network access does not create an account. Signing out of Soda does not terminate SSH sessions or guarantee sign-out from Forgejo. See People and access for changes and revocation.
A lasting development environment
Normal project stop/start and host reboot preserve accounts, homes, SSH host keys, installed tools, shared files, configuration and service data. Existing workloads may need their ordinary native start command after a restart. Persistence is not automatic workload restart, backup or disaster recovery.
Git carries source, migrations and tool/service definitions—not running databases or installed binaries. Merging code does not install tools, apply migrations, restart processes, promote live state or clean up resources. Use ordinary native tools for those actions, with the required project permissions.
Continue with Projects and workspaces or Backups and restoration.