API Documentation

Complete reference for the Town OS systemcontroller API — 77 endpoints across accounts, storage, repositories, packages, systemd, settings, audit, pages, DNS, monitoring, system services, locales, VM images, and status.

Authentication

Authenticate by calling POST /account/authenticate with a username and password. The response contains a Bearer token. Include it in subsequent requests:

Authorization: Bearer <token>

Sessions expire after 7 days of inactivity. There are five auth levels:

Creating an object storage partition is reserved for administrators even though the endpoints inside one are not: a partition roots a permission tree and allocates a btrfs subvolume with a quota, so the grant admits you to the users inside a partition rather than to the decision that it should exist.

Status

Health check and system overview. Unauthenticated callers receive a minimal response with status and needs_setup. Authenticated callers receive the full dashboard payload including filesystem count, package counts, unit status summary, disk usage, external/internal IP, and upgrade availability.

Storage

List filesystems. Accepts pagination parameters plus optional name (prefix filter) and state (user, installed, or uninstalled) in the request body.

Create a new btrfs subvolume. Send name and optional quota (bytes). If quota is 0 or omitted, the system default (50 GB) is used. Reserved names (installed, uninstalled, archives) are rejected.

Modify an existing filesystem. Send name to identify it and a filesystem object with the updated name and/or quota.

Remove a filesystem. Request body: {"name": "mydata"}.

Upload and unpack an archive into a target subvolume. Accepts multipart/form-data with a subvolume field and an archive file. Supports .tar.gz, .tgz, .tar.bz2, .tbz2, .tar.xz, .txz, .tar, .zip, and .7z.

Download an archive of subvolume contents. Returns a streamed archive in the requested format.

List package volumes grouped by package, with optional inclusion of uninstalled volumes.

Delete a specific package volume by internal name.

Delete every volume belonging to one package in a single call, rather than removing them one internal name at a time.

Packages

List all available packages across all repositories. Each entry includes repo, name, version, description, supplies tags, installation status, and whether an upgrade is available. Supports pagination parameters.

List packages grouped by repository. Accepts an optional search query parameter. Returns an array of {"repo": "...", "packages": [...]} groups.

List installed package identifiers. Supports pagination parameters.

Get detailed info for an installed package. Send repo, name, and version. Returns questions, user responses, notes, and note types.

Get the saved question responses for an installed package. Send repo, name, and version. Returns a key-value map of responses.

List available versions for a package. Request body: {"name": "nginx"}. Returns a string array of version identifiers.

List child packages. Send repo and name. Returns a string array.

Get the installation questions for a package. Request body: {"name": "nginx"}. Returns a map of question key to {"query": "...", "type": "..."}.

Get questions for a specific package version. Send repo, name, and version.

Begin the OAuth device flow for an oauth question. Send repo, name, version, and question. The system controller runs the flow’s start step against the provider and returns flow_id, approve_url (open this in the user’s browser), an optional user_code, and interval_ms — how often to poll.

The provider’s URLs come from the package, not from Town OS, so they are checked before they are called: https only, and never an address on the host’s own network.

Poll a flow started above. Send flow_id. Returns status: pending while the user has not approved yet, approved together with the token, or expired once the flow has timed out or its token has already been collected — a flow is single-use. The token is then submitted as that question’s answer to /packages/install, exactly like a typed response.

Preview what an installation will do before committing. Send repo, name, and version. Returns volume details, port mappings, disk usage, quota information, upgrade source version, and a human-readable summary.

Install a package.

Uninstall a package. Send repo, name, version, and optional purge_volumes (boolean) to delete associated data.

Disable an installed package (stop its service). Send repo and name.

Re-enable a disabled package (start its service). Send repo and name.

Delete all data volumes for an installed package. Send repo and name.

Check whether a package has leftover volumes from a previous installation. Send repo and name. Returns has_uninstalled_volumes, uninstalled_versions, and installed_versions.

Delete leftover volumes from previously uninstalled versions. Send repo and name.

List available upgrades for installed packages. Each entry includes installed_version, latest_version, and whether the package definition has changed.

Dismiss the current upgrade notifications. Send an empty JSON object.

Returns the raw YAML package definition. Send repo, name, and version. Returns the file content with Content-Type: text/x-yaml. Returns 404 if the package file does not exist.

List featured packages across all repositories.

Retrieve cached last responses for a package. Send repo and name. Returns the saved responses from a previous uninstall for reuse during reinstallation.

Delete the cached last responses file for a package. Send repo and name.

Pull latest changes for git-seeded volumes of an installed package and restart the dependent service. Send repo, name, and version. Template variables are re-evaluated against saved responses before rebuilding.

Settings

Get all settings as a key-value object.

Get a single setting. Request body: {"key": "default_quota"}. Returns key and value.

Set a setting value. Request body: {"key": "default_quota", "value": "107374182400"}.

Default Settings

Pages

Static site hosting supporting three content source types: archive uploads, container images, and git repositories. Users assign a domain, and the system serves the content via a Caddy container. All mutation endpoints require admin authentication; the list endpoint requires regular authentication.

List all pages with sorting, search, and pagination. Sortable by name, repo URL, branch, domain, source type, status, and timestamps.

Create a new page. Accepts name, source type (archive, container_image, or git), repo URL, branch, domain, container image, and image directory. Source type defaults to archive. Git and container image pages are provisioned asynchronously.

Upload a tar archive of content for an archive-type page. Accepts multipart form with name and archive file. Only valid for pages with source type archive; returns 400 for other source types.

Partial update of a page's repo URL, branch, domain, source type, container image, or image directory. Only provided fields are changed.

Delete a page from the database, remove the webroot symlink, and delete the btrfs subvolume.

Rebuild page content from source. Git pages pull latest changes; container image pages re-extract from the image. Archive pages return 400 (re-upload via /pages/upload instead).

Networks

A network is a named WireGuard overlay paired with a DNS TLD. Packages install into a network, peers join it, and the TLD is what partitions who can resolve what. Network names are DNS-label-safe and capped at 32 characters, because they are reused as WireGuard interface suffixes and systemd unit names.

The home network always exists — it is seeded with the database itself, not created at boot — and it is special in three ways: it cannot be removed or created a second time, it is DNS-only (no WireGuard interface, no subnet, no peers), and peer enrollment on it is refused with a 400. Every account belongs to the home network, so accepting enrollment there would make membership alone a way onto a tunnel — and the stored peer would describe a tunnel that does not exist.

Disabling a network takes down only the transport: the WireGuard interface is not brought up, which cuts remote access, while local DNS resolution and the containers themselves keep running.

List networks. Each entry carries the name, TLD, subnet, the box's own overlay address, public key, listen port, and enabled flag. The private key is never serialized.

Create a network. The subnet is derived deterministically from a box-identity seed and the network name, drawn from 10.64.0.0/10 to stay clear of the ranges consumer routers hand out. Keying on box identity means two Town OS boxes both serving peers pick distinct subnets, so a device joining both never sees a collision. Creating home returns 409 from the TLD-collision check.

Remove a network. Refuses the home network.

Bring the network's WireGuard transport up.

Take the transport down while leaving DNS and the containers running.

Peers

List the peers enrolled on a network.

List peers currently connected, as opposed to merely enrolled.

Enrol a peer. The wireguard grant is what admits a non-admin; per-network scope and per-peer ownership are enforced by the handler. Returns 400 for the home network, which is DNS-only.

Renew a peer's enrollment before its TTL expires. Enrollments have a lifetime and a reaper removes the ones that lapse.

Remove a peer from a network.

The local CA

Download the box's local certificate authority in PEM form. Town OS issues its own leaves for package names, so trusting this certificate is what makes those names work in a browser without warnings. It is deliberately public — a CA certificate is the part you are meant to distribute, and a client needs it before it holds any credential to authenticate with.

Monitoring

Integrated Prometheus, Node Exporter, and Grafana stack for system monitoring. The stack runs as systemd-supervised podman containers with Restart=always.

Returns container status (name, image, running state, port) for each monitoring service. Returns {"status": "disabled"} when monitoring is not configured.

Reaching the dashboard data

There is no reverse proxy through the system controller. Monitoring data is served on its own dedicated port, 5308, and the browser talks to that port directly; the controller's own port (5309) carries only /monitoring/status. What listens on 5308 depends on the configured backend:

• uPlot mode (the default) — a socat forwarder exposes the Prometheus HTTP API on 5308, and the UI queries /api/v1/query_range directly, rendering the charts itself.
• Grafana mode — Grafana listens on 5308 directly through a podman port mapping, and the UI embeds it in an iframe.

TOWN_OS_MONITORING_PORT relocates the dashboard port; TOWN_OS_PROMETHEUS_PORT and TOWN_OS_NODE_EXPORTER_PORT do the same for the two loopback ports.

Locales

Internationalization locale information for the system.

Returns the current locale, list of populated locales, common languages (with native-script names), and extended locales. Uses BCP 47 locale codes.

Object Storage Admin API (gfeh)

Everything above is the Town OS API, which is what an application should normally use. Underneath it, each gfehd partition has an administrative surface of its own: JSON over HTTP on its Unix socket only, never a port.

There is no token and no authentication on this surface. The filesystem permissions on the socket are the access control, so being able to reach it already means being root on the box. The socket lives on the btrfs volume because that is the one filesystem both the gfehd container and the system controller container can see.

gfehd maps its internal errors onto HTTP status codes — 404, 409, 400 — and the Go client maps those back onto sentinel errors, so errors.Is works across the socket boundary.

Where a partition's files live, for a network named <network>:

Client Libraries

Town OS ships with Go and JavaScript client libraries that provide full API coverage. Both clients throw typed errors on non-200 responses using RFC 9457 problem detail.

Go Client

The Go client lives in src/svc/systemcontroller/client.go and implements the Client interface. It supports both Unix socket and HTTP connections.

// Connect via Unix domain socket (production)
client := systemcontroller.InitClient("/run/town-os/systemcontroller.sock")

// Connect via HTTP (development / testing)
client := systemcontroller.FromClient(http.DefaultClient, "http://localhost:5309")

Set client.Token after authenticating. All methods accept a context.Context as their first parameter.

Storage

Repositories

Packages

Systemd

Accounts

Audit, Settings & Upgrades

Archives

Health

Development Reference

The Town OS backend runs on port 5309 with a Vite dev server on port 5173. Use make dev to start the full development environment.

Core Targets

Testing Targets

Build Targets