API and Data Flow

This page explains how tug.sh moves state and actions through the control plane.

Runtime sequence

1. Agent boots and authenticates with a server token.
2. Agent opens outbound WebSocket to api.tug.sh and sends handshake metadata.
3. Dashboard sends user actions to API REST endpoints.
4. API validates permissions and forwards command to the target Agent.
5. Agent executes command and returns structured result (success, logs, optional payload).
6. API updates state and broadcasts events to dashboard clients in real-time.

Key endpoints and data contracts

Server and container state

• GET /v1/servers
  • Returns server list (id, name, status, ip, capacity fields).
• GET /v1/servers/:serverID/containers
  • Returns container snapshot (id, name, image, ports, status, networks, project_id, log_preview).

Runtime actions

• POST /v1/servers/:serverID/containers/:containerID/actions
  • Body: { "action": "start|stop|restart|remove", "db_only": false, "remove_volumes": false, "remove_image": false }
  • API forwards command to Agent and returns command outcome.

TugRouter routes

• GET /v1/servers/:serverID/apps/tug-router/routes
  • Returns route list: { "items": [{ "domain": "app.example.com", "target": "container-name", "port": 80 }] }
• POST /v1/servers/:serverID/apps/tug-router/routes
  • Body: { "domain": "app.example.com", "target_container_id": "container-id", "target_port": 80 }
• DELETE /v1/servers/:serverID/apps/tug-router/routes/:domain
  • Removes a route and reloads TugRouter config through Agent.

Agent command channel (WebSocket)

• API -> Agent command message example:
  • { "type": "container_action", "command_id": "...", "container_id": "...", "action": "restart" }
• Agent -> API command result example:
  • { "type": "command_result", "command_id": "...", "success": true, "logs": ["..."], "payload": { ... } }