tray

NAME

tray — multi-instance coordination hub for connecting SLICC runtimes

DESCRIPTION

The tray connects multiple SLICC instances together into a collaborative session. One instance acts as the leader and others join as followers. The hub runs as a Cloudflare Worker (Durable Object) that handles session coordination, WebRTC signaling, and TURN credential provisioning. Once connected, instances communicate over a peer-to-peer WebRTC data channel.

LEADER / FOLLOWER MODEL

Every tray session has exactly one leader. The leader creates the tray, receives a join URL, and opens a WebSocket to the hub. Followers attach via the join URL and bootstrap a WebRTC connection through the hub's HTTP poll/answer/ice-candidate signaling flow. Once the data channel is established, all communication flows directly between peers — the hub is only used for signaling.

Only the leader can reset the tray. Followers cannot promote themselves. If the leader disconnects, followers remain connected but cannot accept new joiners until the leader reclaims the session. Unclaimed trays expire after one hour.

HOST COMMAND

The host command displays and manages tray state.

host              # show leader/follower state, join URL, connected followers
host reset        # disconnect all followers and create a fresh tray session

When running as leader, host prints the join URL and lists connected followers with their runtime IDs. When running as follower, it shows the connection state (connecting, connected, or error) and the leader's runtime information.

REMOTE BROWSER TARGETS

All connected instances advertise their browser tabs to the tray. The leader maintains a merged target registry (TrayTargetRegistry) and broadcasts it to all participants. This means playwright-cli tab-list shows tabs from ALL connected instances — local and remote.

Remote tabs are identified by composite target IDs in the format runtimeId:localTargetId. For example:

[abc123:4A3B...] https://example.com "Example" [remote:abc123]
[leader:7F2C...] https://other.com "Other"    [remote:leader]

CDP commands (evaluate, click, screenshot, etc.) route transparently over the tray data channel. You target remote tabs the same way you target local ones — just use the composite targetId:

playwright-cli screenshot --tab=abc123:4A3B...
playwright-cli eval --tab=abc123:4A3B... "document.title"

OPENING TABS ON REMOTE RUNTIMES

Use the --runtime flag on open, tab-new, or playwright-cli open / playwright-cli tab-new to open a browser tab on a remote instance:

playwright-cli open https://example.com --runtime=follower-abc123
playwright-cli tab-new https://example.com --runtime=follower-abc123

The remote instance creates the tab in its local browser, and the resulting composite targetId is returned so you can interact with it via CDP.

RSYNC OVER TRAY

The rsync command syncs files between local VFS and a remote tray runtime's VFS. File operations are sent over the tray data channel as filesystem requests.

rsync /workspace follower-abc123:/workspace          # push local → remote
rsync follower-abc123:/workspace/project /workspace  # pull remote → local
rsync --delete /shared leader:/shared                # push with delete
rsync --dry-run -v /workspace r:/workspace           # preview changes

• --dry-run, -n

  Show what would be transferred without doing it.

• --delete

  Delete files in destination that don't exist in source.

• --verbose, -v

  Show detailed per-file output.

The remote side is identified by the runtimeId:/path syntax. One side must always be local — remote-to-remote sync is not supported. Requires an active tray connection.

TELEPORT OVER TRAY

Teleport transfers browser cookies from a follower's browser back to the leader, enabling authentication handoff. The human authenticates on the follower's browser (which they can physically interact with), and cookies are transferred back to the agent's browser session.

playwright-cli teleport --start="login\\.example" --return="dashboard" --timeout=120
playwright-cli teleport --off
playwright-cli teleport --list

The --start regex triggers teleport when the leader tab URL matches (e.g. a login redirect). The URL is opened on a follower for the human to complete auth. When the follower's URL matches --return, cookies and page storage are captured and applied to the leader's browser. Teleport can also be armed inline via navigation commands:

playwright-cli open https://app.example.com --teleport-start="login" --teleport-return="dashboard"
playwright-cli goto --tab=ID https://app.example.com --teleport-start="sso" --teleport-return="callback"

HUB INFRASTRUCTURE

The tray hub is a Cloudflare Worker with a Durable Object (SessionTrayDurableObject) that manages tray state. Each tray session produces three capability URLs:

• controller — used by the leader to attach and open a WebSocket
• join — shared with followers to bootstrap their WebRTC connections
• webhook — for external services to send events into the tray

TURN credentials are fetched from Cloudflare's TURN service and cached with TTL-based refresh. ICE servers are provided to followers during the signaling attach step.

SEE ALSO

float, host, rsync, playwright-cli teleport