Documentation GuidesAPI prototype v1.0.0
REST, SSE & WS API Reference
Complete API reference for workstation instances, Docker resources, SSE telemetry streams, and WebSockets.
REST, SSE & WS API Reference
The prototype backend exposes a unified REST and real-time streaming API. All endpoints are prefixed with /api and bind strictly to 127.0.0.1.
http
# Healthcheck & Architecture Status
GET http://127.0.0.1:8080/api/health
📋 Categorized Endpoints Reference
| Domain | Method | Endpoint | Description |
|---|---|---|---|
| System | GET | /api/health | Service health status and system runtime info. |
| System | GET | /api/config | Sanitized runtime configuration (credentials excluded). |
| System | GET | /api/system/fs?path=... | Host directory file browser with path containment. |
| System | GET | /api/system/runtimes | List available OCI runtimes registered on the Docker daemon. |
| Catalog | GET | /api/catalog/presets | List curated workstation and database presets. |
| Catalog | GET | /api/catalog/ports/next | Scans host TCP ports and returns next available free port. |
| Instances | GET | /api/instances | List all managed workstations and headless services. |
| Instances | POST | /api/instances | Provision a new workstation or service container. |
| Instances | GET | /api/instances/:id/inspect | Low-level kernel, namespace, and capability inspection. |
| Instances | GET | /api/instances/:id/compose | Real-time synthesized Docker Compose v3.8 spec. |
| Instances | POST | /api/instances/:id/compose/apply | Apply edited Docker Compose configuration to instance. |
| Lifecycle | POST | /api/instances/:id/:action | Power actions (start, stop, restart, pause, unpause). |
| Lifecycle | DELETE | /api/instances/:id?delete_volumes=... | Destroy container (preserves named volumes by default). |
| Snapshots | GET / POST | /api/instances/:id/snapshots | List or create point-in-time container image snapshots. |
| Snapshots | POST | /api/instances/:id/clone | Clone instance with new identity and next free port. |
| Resources | GET / POST | /api/images, /api/images/pull, /api/images/prune | Docker images inspection, pull, and dangling layer pruning. |
| Resources | GET / POST | /api/volumes, /api/volumes/prune | Docker named volume management and deep pruning. |
| Resources | GET / POST | /api/networks, /api/networks/prune | Docker bridge networks and container connect/disconnect. |
| Telemetry | GET | /api/instances/:id/stats | Real-time SSE metrics stream (cpu_percent, memory_usage_mb). |
| Telemetry | GET | /api/instances/:id/logs?tail=150 | Real-time SSE streaming stdout/stderr container logs. |
| Terminal | GET | /api/instances/:id/terminal | In-browser WebSocket root PTY session (xterm.js). |
⚙️ Environment Variables Reference
| Variable | Default | Purpose |
|---|---|---|
PORT | 8080 | HTTP daemon listening port on host. |
BIND_HOST | 127.0.0.1 (0.0.0.0 in Docker) | Network interface for the management daemon listener. |
DEFAULT_INSTANCE_BIND_IP | 127.0.0.1 | Host loopback interface used for workstation desktop ports. |
DEFAULT_NETWORK | prototype-net | Default Docker bridge network created automatically on boot. |
BASE_PORT | 3000 | Starting port checked by the loopback port scanner. |
DEFAULT_SHM_SIZE_MB | 1024 | Default /dev/shm shared memory allocation (in MB). |
APP_TITLE | prototype | Branding title displayed in header and browser tabs. |