Skip to content
sistemo.io beta
GitHub Docs Quickstart

Browser terminal

Open an interactive shell into a running machine from the dashboard — no SSH client, no public host ports. The browser talks to the control plane over WebSocket; the API proxies to the private host-agent over the mesh.

Dashboard

  1. Open a running machine.
  2. Open the Terminal tab.
  3. Type as in a normal shell. Resize the pane if needed.

Requirements:

  • Machine state is running (not stopped / provisioning / error).
  • You are signed into the dashboard (session cookie). Terminal is not meant for raw API-key clients.

How it works (short)

Browser (xterm.js)
    │  WebSocket + one-time ticket
    ▼
Control plane  GET /v1/machines/{id}/terminal?ticket=…
    │  WireGuard only
    ▼
Host-agent terminal  →  shell inside the microVM
  1. Dashboard requests a short-lived WS ticket for the machine (POST /v1/machines/{id}/terminal-session).
  2. Browser connects to GET /v1/machines/{id}/terminal?ticket=….
  3. Ticket is single-use (~30s life) — replay is rejected.
  4. Control plane upgrades the connection and relays to the host-agent. The browser never sees the host address.

API (session / advanced)

Most users only need the dashboard. For integrators building a custom UI:

1. Issue a terminal session

POST /v1/machines/{id}/terminal-session

Auth: session or full API key (same as other mutations). Machine must exist and be yours.

Response shape (illustrative):

{
  "ticket": "<short-lived-jwt>",
  "machine_id": "…",
  "ws_path": "/v1/machines/…/terminal"
}

2. Open the WebSocket

GET /v1/machines/{id}/terminal?ticket=<ticket>

Upgrade to WebSocket. Pass the ticket once. After connect, binary/text frames are a raw PTY stream (as used by xterm.js).

If the machine is not running → 409. Invalid / reused ticket → 401.

Security notes

  • Host-agent stays on the private mesh; not exposed to the public internet for terminal.
  • Tickets are short-lived and single-use to limit steal-and-replay.
  • Prefer dashboard for humans; prefer exec (POST /v1/machines/{id}/exec or SDK run()) for automation.