Quick Start

This guide walks you from a fresh install to a Simulator streaming in your browser and controllable from the CLI.

1. Open The UI

After installing, start or reuse the project daemon and open the browser client:

simdeck ui --open

The command prints JSON:

{
  "ok": true,
  "projectRoot": "/path/to/app",
  "pid": 12345,
  "url": "http://127.0.0.1:4310",
  "started": true
}

Two listeners run inside the daemon:

• HTTP on --port (default 4310) for the REST API and the static React client.
• WebTransport on port + 1 (default 4311) for binary video frames. The server generates a self-signed certificate per session and advertises its hash through GET /api/health.

2. Pick A Simulator

The opened UI lists every simulator. You can also list and boot from the CLI:

simdeck list
simdeck boot <udid>

To focus a specific simulator in the browser, add ?device=<UDID> to the UI URL.

First-frame delay

On a cold boot the daemon has to launch the Simulator, attach the private display bridge, and wait for a keyframe before video flows. The first frame typically shows up within a second; subsequent reloads of the same Simulator are near-instant.

3. Drive It

The same daemon backs browser controls, CLI commands, and tests:

simdeck open-url <udid> https://example.com
simdeck launch <udid> com.apple.Preferences
simdeck tap <udid> --label "Continue" --wait-timeout-ms 5000
simdeck describe <udid> --format agent --max-depth 2

Coordinate commands use screen points by default. Pass --normalized when sending 0.0..1.0 coordinates:

simdeck tap <udid> 0.5 0.5 --normalized

See the full CLI Reference for every command and flag.

What just happened?

When you opened the UI:

1. The browser fetched /api/health and learned where the WebTransport endpoint lives.
2. It opened a WebTransport session at wss://127.0.0.1:4311/wt/simulators/<udid> and pinned the self-signed certificate by hash.
3. The Rust transport hub asked the native bridge for a fresh keyframe and started forwarding binary video packets.
4. Touch and keyboard events round-trip through POST /api/simulators/<udid>/touch and /key, which the native bridge replays through HID.

You can read more about the layers involved in Architecture and WebTransport.

Common follow-ups

• Run the server on a LAN-reachable port. See LAN Access.
• Manage the warm native host explicitly. See Project Daemon.
• Write JS/TS app tests. See Testing.
• Stream is choppy or stuck on a black frame. See Video Pipeline and Troubleshooting.
• Embed the client in VS Code. See the VS Code extension.