Develop
Architecture
SubakoOS is a native host-management service composed of a SvelteKit interface, a FastAPI application, a SQLite database, and a constrained privilege boundary.
Runtime layout
| Layer | Responsibility |
|---|---|
| Browser UI | Operator workflows, live status, validation, and confirmations |
| FastAPI backend | Authentication, authorization, API routes, orchestration, and WebSockets |
| Service layer | Host-tool adapters and application business logic |
| SQLite | Users, preferences, tasks, metrics, notifications, and plugin state |
| Privileged helper | Allowlisted operations that genuinely require root |
| systemd | Service lifecycle and scheduled task execution |
The release bundle installs under /opt/subakoos, while mutable state belongs under /var/lib/subakoos and configuration under /etc/subakoos.
Privilege boundary
The application service runs as the dedicated subakoos account. It does not run as root. Privileged subprocesses use non-interactive sudo -n and a narrow policy installed by the bootstrap.
Requests also cross application-level controls:
- PAM authentication establishes the user.
- Route policy checks the required module or administrator role.
- Sensitive operations can require recent password confirmation.
- Request schemas and service code validate host-facing values.
- The helper accepts only known operations and constrained arguments.
- Audit records capture security-relevant actions.
HTTP and real-time traffic
REST endpoints live under /api/v1. WebSocket routes carry live metrics, notifications, logs, tasks, and terminal sessions. Production traffic should arrive through a TLS reverse proxy on the configured frontend origin.
Plugins
Trusted plugins provide manifests, lifecycle hooks, routes, and optional frontend or event behavior. The loader tracks enabled state and validates plugin identity. Treat plugin installation like installing server software: review its source, permissions, and provenance.
Why native installation
SubakoOS manages the host's PAM users, systemd services, devices, network stack, filesystems, and rootless Podman runtime. Containerizing the manager would introduce a second namespace and require broad host mounts or privileges that undermine the intended boundary.
Source layout
Core code is split between backend/ and frontend/. Built-in plugins and SDKs live under plugins/; installation, release, and repository checks live under scripts/.
Continue with the API guide for programmatic access.