Concepts

The Motion Tunnel

Self-hosted boxes are usually behind NAT, so the hub can't reach in. The box dials out instead: the tunnel agent opens an outbound WebSocket to wss://motionis.xyz/api/tunnel/connect and authenticates with the connect token.

Over that single connection the hub multiplexes:

• HTTP, streamed — so Server-Sent Events (the AI chat stream) flush live and large downloads don't buffer whole in memory.
• WebSocket streams — the terminal (PTY), file-watch, and AI stream, with binary/text preserved.

A heartbeat (ping/pong every ~25s) detects a dead box within ~50s so the dashboard's online/offline status is accurate, and the agent reconnects with exponential backoff.

Hub vs box

The hub (motionis.xyz) authenticates you and routes to your workspaces; it never bypasses the daemon to touch your files. The box (your machine) runs the actual workspace — IDE, daemon, terminal, files — confined to its --root.

Cloud and self-hosted boxes are the same software; only the path the hub uses to reach the daemon differs (a container address vs the tunnel).

Shared services

• Vault — the hub holds your end-to-end encrypted vault blob (it never has the plaintext or your passphrase) and seeds it into the workspace, where you unseal it locally.
• Networking / domains — bring a DNS token (Cloudflare) to manage records and give deployments subdomains.
• Metrics — CPU, RAM, and network come from the box's daemon over the tunnel.

Where to go deeper

The hub, vault custody, ingress, and deployment internals are covered in the repository's architecture notes (docs/PLATFORM-MODEL.md, docs/ARCHITECTURE.md).