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 three auth levels:

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.

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 all available IANA timezone names for use in package configuration.

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.

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).

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.

Reverse proxy to the local Grafana instance, stripping the /monitoring/grafana prefix from the URL path. Returns 503 if monitoring is not configured. This endpoint bypasses authentication.

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.

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