Skip to main content
POST
Open a live connection to a task's machine

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

taskID
string<uuid>
required
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Body

application/json
protocols
integer<int64>[]
required

The live protocol versions the client speaks. The answer names the highest one the machine speaks too.

Required array length: 1 - 8 elements
start_sandbox
boolean

Start a stopped sandbox first. Send true once, on the first call after the person chose to start, and false or nothing on every later call of that attempt.

Response

OK

A live connection to the task's machine: ready, starting or stopped.

frame_key
string | null
required

The key that seals every frame of a socket the relay joins, a task on a computer's: 64 lower-case hex characters, the 32 bytes of a ChaCha20-Poly1305 key. Null: the API answers this socket itself, a sandbox's, and frames are not sealed.

Pattern: ^[0-9a-f]{64}$
live_connection_id
string<uuid>
required

The connection's id.

preview_url_template
string | null
required

The address of a port on the machine, with {port} in its leftmost label to fill with an integer from 1 to 65535, or null when the machine's ports cannot be reached from the client.

protocol
enum<integer>
required

The live protocol version the socket speaks: the highest one both the client and the machine speak.

Available options:
1,
2
state
enum<string>
required

The machine can be dialled now: open the socket before ticket_expires_at.

Available options:
ready
ticket
string
required

Opens the socket once, until ticket_expires_at. Offer the WebSocket subprotocols bearer and the ticket; never put it in an address.

Pattern: ^live\.v1\.[0-9a-f-]{36}\.client\.[0-9]+\.[0-9a-f]{64}$
ticket_expires_at
string<date-time>
required

When the ticket stops opening the socket, 30 seconds after this answer. It bounds opening the socket, not its life.

websocket_url
string<uri>
required

The absolute wss (ws locally) address to dial: /live/{live_connection_id}.