API reference
How to authenticate against Udon's HTTP API, the roles it checks, and its main HTTP and WebSocket endpoints.
The daemon udond serves a JSON HTTP API on the same HTTPS port as the web UI (4443 by
default). The web UI is built on this API, and it is stable enough to script against. The tables
below cover the main endpoints; the pages under this section document every one, with its request
and response.
Authentication
Auth is a session cookie named udon_session. It is HttpOnly, SameSite=Strict, and marked Secure
over TLS. Sign in with POST /api/auth/login; the response sets the cookie. Send the cookie on
every later request. WebSocket upgrades use the same cookie.
Every endpoint also accepts Authorization: Bearer <token>. Send an X-Udon-Client header with
the login request to get a token in the response body instead of the cookie.
Roles, from least to most access:
viewer: read most data.operator: viewer, plus run and manage containers, images, and files.admin: operator, plus user management, system and network settings, privileged actions.
An endpoint's required role is listed below. A higher role always satisfies a lower requirement.
Errors come back as JSON with a human-readable message and an HTTP status (400 invalid input, 401 not signed in, 402 license locked, 403 wrong role, 404 missing, 409 conflict, 423 Admin Privileges or Full Disk Access missing, 503 engine or helper unavailable, or an update still finishing).
Health and setup
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /health | none | Daemon liveness and version. |
| GET | /api/setup | none | Whether the first account still needs creating. |
| POST | /api/setup | none | Create the first admin (only before any user exists). |
Auth
| Method | Path | Role | Purpose |
|---|---|---|---|
| POST | /api/auth/login | none | Sign in with username and password. |
| POST | /api/auth/logout | viewer | End the session. |
| GET | /api/auth/me | viewer | The signed-in user. |
Users
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/users | admin | List users. |
| POST | /api/users | admin | Create a user (username, password, role). |
| POST | /api/users/:id/role | admin | Change a user's role. |
| POST | /api/users/:id/disabled | admin | Enable or disable a user. |
| POST | /api/users/:id/password | admin | Reset a user's password. |
| POST | /api/users/:id/remove | admin | Delete a user. |
| POST | /api/me/password | viewer | Change your own password. |
Containers and images
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/system/engine | viewer | Container engine status. |
| GET | /api/containers | viewer | List containers. |
| GET | /api/containers/:id | viewer | Inspect a container (raw engine JSON). |
| GET | /api/containers/:id/stats | viewer | Resource stats. |
| GET | /api/containers/:id/logs | viewer | Recent logs as text. |
| POST | /api/containers | operator | Run a container from a RunSpec. |
| POST | /api/containers/:id/start | operator | Start. |
| POST | /api/containers/:id/stop | operator | Stop. |
| POST | /api/containers/:id/restart | operator | Restart. |
| POST | /api/containers/:id/kill | operator | Kill. |
| POST | /api/containers/:id/remove | operator | Remove (force optional). |
| GET | /api/images | viewer | List images. |
| POST | /api/images/pull | operator | Pull an image by reference. |
| POST | /api/images/delete | operator | Delete an image by reference. |
| GET | /api/networks | viewer | List container networks. |
| POST | /api/networks | operator | Create a network. |
| POST | /api/networks/:name/delete | operator | Delete a network. |
A RunSpec carries image plus optional name, command, ports, env, volumes, cpus,
memory, workdir, network, and a set of advanced fields (entrypoint, user, capabilities, DNS,
mounts, tmpfs, devices, extra flags).
System
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/version | viewer | Daemon version and commit. |
| GET | /api/system/info | viewer | Hardware and OS facts. |
| GET | /api/system/network | viewer | Network interface summary. |
| GET | /api/system/settings | viewer | Read-only host settings snapshot. |
| GET | /api/audit | admin | Activity log. Query range (24h/7d/30d/all), limit, offset. |
| GET | /api/system/desktop | admin | Screen Sharing status and connect URL. |
| POST | /api/system/power/sleep | admin | Sleep the Mac. |
| POST | /api/system/power/display-sleep | admin | Sleep the display. |
| POST | /api/system/power/restart | admin | Restart the Mac. |
| POST | /api/system/power/shutdown | admin | Shut down the Mac. |
| GET | /api/updates | viewer | The last update check's result. |
| POST | /api/updates/install | admin | Install the update and restart. |
Network configuration
Admin, and requires Admin Privileges. Every value is validated by the root helper and run as argv.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/system/network/services | List configurable network services. |
| POST | /api/system/network/services/:service/dns | Set DNS servers. |
| POST | /api/system/network/services/:service/ipv4 | Switch to DHCP or set a manual IPv4. |
| POST | /api/system/network/services/:service/enabled | Enable or disable the service. |
Admin Privileges
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/system/privileged | viewer | Helper status and the list of privileged actions. |
| POST | /api/system/privileged/:key | admin | Apply one allowlisted action (choice on/off/set, optional value). |
Storage and files
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/storage | viewer | Disks, volumes, container volumes, roots, and mounted shares. |
| GET | /api/storage/smart/:id | operator | SMART report for a disk. |
| POST | /api/storage/eject | admin | Eject a removable disk. |
| POST | /api/storage/mount | admin | Mount a network share. |
| POST | /api/storage/unmount | admin | Unmount a network share. |
| GET | /api/storage/exports | viewer | Folders shared over SMB. |
| POST | /api/storage/exports | admin | Share a folder over SMB (path, name, readOnly, guestAccess). |
| POST | /api/storage/exports/remove | admin | Stop sharing a folder. |
| GET | /api/storage/fs/list | operator | List a directory (root, path). |
| GET | /api/storage/fs/read | operator | Read a text file (preview, capped). |
| GET | /api/storage/fs/download | operator | Download a file (supports range requests). |
| POST | /api/storage/fs/upload | admin | Upload a file (root, path, name, raw body). |
App catalog
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/catalog | viewer | Installable apps from the catalog. |
Dashboard, branding, icons, extensions
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/bento/widgets | viewer | Dashboard widgets with cached output (script hidden for non-admins). |
| POST | /api/bento/widgets | admin | Create a widget. |
| POST | /api/bento/widgets/:id/update | admin | Edit a widget. |
| POST | /api/bento/widgets/:id/delete | admin | Delete a widget. |
| POST | /api/bento/widgets/:id/run | operator | Run a widget now. |
| GET | /api/branding | none | Sign-in page branding: server name, headline, description and background. |
| PUT | /api/branding | admin | Set the server name. |
| GET | /api/icons/container/:name | viewer | Custom container icon. |
| PUT | /api/icons/container/:name | operator | Upload a container icon. |
| DELETE | /api/icons/container/:name | operator | Clear a container icon. |
| GET | /api/extensions | viewer | Installed shell extensions. |
Tailscale
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/tailscale | viewer | Status, peers, and remote-access state. |
| POST | /api/tailscale/settings | admin | Apply preferences (accept routes/DNS, SSH, shields, exit node, hostname). |
| POST | /api/tailscale/login | admin | Start the login flow, returns an auth URL. |
| POST | /api/tailscale/logout | admin | Disconnect from the tailnet. |
| POST | /api/tailscale/connect | admin | Bring the tailnet up or down. |
Packages and search
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/brew | viewer | Installed Homebrew packages. |
| GET | /api/brew/search | viewer | Search Homebrew (q). |
| GET | /api/dockerhub/search | viewer | Search Docker Hub (q). |
Metrics
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /api/metrics | viewer | One host metrics snapshot. |
| GET | /api/metrics/stream | viewer | Server-sent events, a sample every two seconds. |
WebSocket endpoints
These upgrade over the session cookie or a bearer token, and a browser must open them from the dashboard's own address.
| Path | Role | Purpose |
|---|---|---|
/api/containers/install | operator | Live install output; first message is a RunSpec. |
/api/containers/update | operator | Live output of a batch container update. |
/api/containers/logs?id=&tail= | viewer | A container's log, followed live. |
/api/terminal | admin | Interactive shell on the host. |
/api/desktop | admin | VNC bridge to the Mac's Screen Sharing. |
/api/brew/exec | admin | Live output of a Homebrew install, upgrade, or uninstall. |
The terminal socket carries binary frames both ways, and accepts a text frame
{"type":"resize","cols":N,"rows":N} to resize the pseudo-terminal.