Expand description
A client for the Town OS control plane, the HTTP API served by
systemcontroller on port 5309.
Every endpoint answers 200 on success — including the ones with no body — so
anything else is a refusal and becomes an Error::Status. Authentication is
a bearer token obtained from Client::authenticate; it is a 7-day JWT that
slides forward on use.
The module split follows the control plane’s own route groups: dns,
storage (object storage plus the btrfs volumes underneath it), and
networks (the WireGuard overlays a client enrolls into).
Modules§
- dns
- DNS: the
rolodexzones the box is authoritative for, plus the blocklists it filters resolution through. - networks
- WireGuard overlays, and the enrollment this client joins one through.
- status
- Box-wide status: the overview counters and the core services.
- storage
- Object storage —
gfeh— and the btrfs volumes beneath it.
Structs§
- Account
- Authenticated
- Client
- A handle on one Town OS box.
- Filesystem
- A btrfs subvolume. Object storage partitions are backed by these, and the tab shows them together so a quota is legible next to what fills it.
- Filesystem
Page - One page of
POST /storage. - Ping
- The system overview from
GET /status/ping. - Problem
- An RFC 9457 problem detail, when the server sent one.
- Session
- System
Service - A core system service and its container state, from
GET /system-services. - Unit
Counts
Enums§
Constants§
- DEFAULT_
PORT - The port
systemcontrollerlistens on unlessTOWN_OS_LISTENsays otherwise. - GRANT_
GFEH - The grant that permits administering object storage.
- GRANT_
WIREGUARD - The grant that permits enrolling and refreshing WireGuard peers.
- MIN_
PASSWORD_ LENGTH - The shortest password the box will accept.
Functions§
- base_
url_ for - Builds the base URL for a host entered by a user.
- format_
bytes - Renders a byte count the way an operator reads a quota, with 0 meaning unlimited rather than empty.