Remote Namespace

Remote Namespace

The /remote socket.io namespace provides one-time-ticket binary streaming sessions — built for remote-control use cases: an agent streams binary frames (e.g. screen captures) to viewers, and viewers send input events back to the agent.

Flow

1. An authenticated client on the main namespace requests a ticket:

   client → server: REMOTE_TICKET_REQUEST { session_id?, machine_id?, role: 'agent'|'viewer' }
   server → client: REMOTE_TICKET { ok, session_id, ticket, role, expires_in }
   

   With auth enabled, the socket must authenticate first; the ticket inherits the socket's realm. Tickets are single-purpose, random, and expire after 60 s by default (remote: { ticket_ttl_ms }).

2. The remote party connects to /remote and presents the ticket:

   socket → server: auth { ticket, session_id }
   server → socket: auth_ok    { session_id, role }
                  | auth_error { message }       // invalid/expired/mismatched
   

   The ticket must match the session and the role it was issued for.

3. Streaming:

   Event	Direction	Payload
   frame	agent → all viewers	binary (Buffer/ArrayBuffer) frame data
   input.mouse	viewer → agent	mouse event object
   input.keyboard	viewer → agent	keyboard event object

   One agent per session, any number of viewers; frames fan out to the session's viewer room only.

Session inspection

Server-side:

server.remote.getSession(sessionId);   // { session_id, agent_connected, viewer_count }
server.remote.listSessions();
server.remote.issueTicket({ session_id, realm, machine_id, role });

Security notes

• Tickets are the only way into /remote — there is no password fallback.
• Issuing a ticket requires an (authenticated, when auth is on) main- namespace connection, so realm/role policy gates who can start sessions.
• Expired or reused-for-the-wrong-session tickets are rejected with auth_error.