Web UI

Runix includes a browser-based dashboard backed by an HTTP API and a WebSocket stream.

Launch

# Default: localhost:9615
runix web

# Custom address
runix web --listen 0.0.0.0:8080

# Open a browser after startup
runix web --open

runix web asks the daemon to start the web server. The server keeps running in the daemon after the CLI exits.

Server Surface

The implementation lives in runix/internal/web/.

File	Responsibility
server.go	Chi router, auth routes, API routes, static frontend, WebSocket lifecycle
api.go	REST handlers for processes, logs, and system metrics
auth.go	Session-based browser login flow and auth status endpoints
websocket.go	Real-time broadcast hub for process summaries
frontend/index.html	Embedded dashboard
frontend/login.html	Embedded login page

HTTP Routes

Public routes:

Method	Path	Notes
GET	/login	Login page for browser sessions
POST	/api/auth/login	Session login for basic auth mode
POST	/api/auth/logout	Clears the current session
GET	/api/auth/status	Reports auth mode and session state

Protected API routes under /api/v1:

Method	Path	Description
GET	/api/v1/processes	List all managed processes
GET	/api/v1/processes/{id}	Get one process by ID or name
POST	/api/v1/processes	Create and start a process from a ProcessConfig JSON body
POST	/api/v1/processes/{id}/stop	Stop a process
POST	/api/v1/processes/{id}/restart	Restart a process
POST	/api/v1/processes/{id}/reload	Gracefully reload a process
DELETE	/api/v1/processes/{id}	Stop and remove a process
GET	/api/v1/processes/{id}/logs	Return tailed logs
GET	/api/v1/system/metrics	Return system-wide metrics

The WebSocket endpoint is:

Method	Path	Description
GET	/ws	Streams periodic process summaries

WebSocket Payload

The server broadcasts a process_list message every 2 seconds when clients are connected.

{
  "type": "process_list",
  "processes": [
    {
      "id": "abc12345",
      "numeric_id": 1,
      "name": "api",
      "runtime": "go",
      "state": "running",
      "pid": 48291,
      "restarts": 0,
      "cpu_percent": 0.4,
      "memory_bytes": 14876672,
      "mem_percent": 0.1,
      "threads": 9,
      "fds": 12,
      "uptime": 30000000000
    }
  ],
  "timestamp": 1760000000
}

Durations are serialized as nanoseconds because the payload uses Go time.Duration.

Authentication

The web UI uses the global security.auth settings. When auth is enabled:

• Browser requests are redirected to /login
• API requests return 401 JSON
• Successful login creates a session cookie
• Token auth protects the API and WebSocket, but browser form login is intentionally disabled

Legacy web.auth still exists in the config structs for compatibility, but current auth behavior is driven by security.auth.

Frontend Delivery

The dashboard is compiled into the Go binary with //go:embed, so there is no separate frontend build artifact to deploy.

Related Docs

• API Schema
• Web And Auth Configuration
• Web Command