Share a workspace live: roles, waiting room, terminal grants

Updated 2026-09-12

Share the workspace state

When you share a SpeakCode workspace, guests receive a real canvas and native terminal views. SpeakCode replicates workspace state and streams terminal output instead of sending a video of your screen. A guest can watch Claude Code in its terminal while you continue arranging the project around it.

The host remains authoritative. Guests request edits, the host checks those requests, and accepted changes flow back to the shared workspace. Terminal input follows a similar route: a guest's keystrokes must pass the host's checks before reaching the actual terminal process.

The terminal process continues to run on the host. A guest renders its output locally rather than spawning an independent copy of your shell or agent. That distinction matters when you invite someone to help: granting terminal input lets them act in the host's session. The team workspace overview places this workflow in the context of conducting agents together.

For the desktop workflow below, use the native macOS app on macOS 26 or later. Start with a workspace and terminal you are ready to share, then decide who needs to observe, edit the canvas, or type into a specific terminal.

Roles control workspace participation

SpeakCode exposes three guest roles, enforced by the host:

Editor permissions cover allowed card, frame, drawing, and note edits. They do not give a guest unrestricted authority to spawn agents, approve actions, or submit privileged command events. Editors may delete terminal cards; permission to create new terminals is a separate session setting with per-participant overrides. Moving or resizing an existing terminal card is ordinary editing.

Blocking removes both current terminal grants and grants suspended during a disconnect. A blocked guest cannot regain typing access later merely by reconnecting with an old grant. Blocking and hard ejection are separate controls: use the roster's eject control when you need to remove a connection. Do not treat a role change as a way to retract content someone already received.

On a fresh installation, new joiners default to viewer, the waiting room is enabled, and editor terminal creation is off. You can change the app-wide defaults in Settings → Collaboration. A sharing session takes those defaults when it starts; use the live share popover's Permissions section to change the current session.

Admit people with an explicit role

With the waiting room enabled, a new unclassified joiner waits for the host. Pending guests receive no canvas content, cannot submit authorized edits or terminal input, and see a waiting-room overlay. In the host's collab roster, they appear in the waiting-to-join group.

Admit each person explicitly as viewer or editor. Admission sends the workspace catch-up so they can enter the live canvas. Denial blocks and ejects the joiner in hosted sharing. The local development backend does not implement hard ejection, so do not assume identical removal behavior there.

The waiting room has a privacy limit: pending guests may see other guests' cursors or names through presence traffic, although they do not receive canvas content. Treat an invite link as a bearer secret and send it to the people you intend to admit.

Turning waiting-room approval on during an existing session preserves the effective roles of people already connected. It governs unclassified joiners; it does not send the existing roster back into the waiting room.

Typing requires a second, terminal-specific permission

An editor role alone never authorizes terminal typing. You must grant that participant access to the particular terminal through the host's roster. A grant for a helper terminal does not authorize another terminal on the canvas. Creating a terminal card also does not imply permission to type into it.

There are two independent host-side checks. First, incoming terminal input is accepted only on the host's connection and only when authorization succeeds. Second, the host checks that the sender is currently an editor and holds a grant for that terminal. Missing authorization defaults to denial; the guest's own interface is not the authority.

The roster exposes a per-terminal grant toggle for editors. Open the terminal on the host first; a grant only authorises typing into a terminal that is already running. After the grant, the guest still uses the host's terminal process; they have not received a separate local execution environment.

Configure guest-input safety

A typing grant answers who may send input. The guest-input safety controls evaluate the command lines they send. Built-in dangerous-command rules combine with host-defined custom rules, with three possible actions:

• Flag: record the incident and allow the line.
• Hold: pause the line until the host approves or rejects it.
• Block: prevent the line from proceeding.

The host can disable built-in rules or change their actions, but cannot delete them. A per-guest trust setting adjusts enforcement: trusted guests have dangerous commands flagged, normal uses ordinary enforcement, and strict escalates flags to blocks. Per-terminal scope further adjusts behavior, from open monitoring through normal and restricted to observe-only, which blocks all guest input.

These settings work after the role and grant checks; an open monitoring scope does not give an ungranted viewer typing rights. Repeated blocks trigger automatic escalation, and the moderation UI presents the guest-input trail and incidents. For a first session, review the effective guest and terminal settings before delegating a command, and stay available to resolve held input.

Local network and internet sharing

Local-network sharing works out of the box. For internet sharing, you or someone on your team must run a LiveKit server plus the token service. Hosted mode is off by default, and the app ships with no backend URL; both sides must enable hosted mode and enter both URLs under Settings → Collaboration.

In Settings → Collaboration, enter the values supplied by the operator of that backend. Set these fields:

Replace yourdomain.com with the actual deployed domain. Both apps need the appropriate backend configuration. Select Test connection, which checks the token service's /healthz endpoint. This verifies that endpoint; it is not proof that terminal traffic can traverse every firewall along the route.

Complete both URL fields. Hosted mode with a blank or invalid URL silently falls back to the local loopback development server. That can make an incomplete internet setup look like a failed remote invitation.

Running the backend requires a server, a domain with DNS control, TLS, and network access for LiveKit and TURN. If guests connect but canvas traffic does not flow, check TURN and firewall configuration, including UDP 3478 and UDP 50000–60000. Have the backend operator investigate connectivity rather than changing guest roles to compensate for a network problem.

Host a session

1. Open the workspace you intend to share. Open each terminal that guests need to watch at least once; the host does not automatically start an unseen terminal just because a viewer looks at its card.
2. For internet sharing, configure the hosted server fields above and run Test connection. For local-network sharing, make sure your teammate is on the same network.
3. Open the collaboration control in the top bar and start sharing. Inspect the live popover's Permissions section: choose the default role, enable the waiting room if desired, and decide whether editors may create terminals.
4. Copy the generated invite link and send it to the intended guest. The link opens SpeakCode and identifies the shared workspace.
5. In the waiting-to-join group, admit the guest with an explicit role. Choose viewer for someone reviewing output; choose editor for someone helping arrange or edit the canvas.
6. If an editor needs to type, grant only the intended terminal in that participant's roster controls. Review the relevant input-safety settings and have them send an agreed, harmless input first.
7. Watch the shared terminal response and verify that both of you are looking at the intended session before handing over the next task.

Join a session

1. Use SpeakCode on your Mac. For an internet session, configure the backend URLs supplied for the session and test the connection.
2. Open the host's invite link. The link shape is speakcode://join?room=speakcode-<canvasUUID>&secret=<secret>; use the generated link rather than inventing identifiers.
3. If the waiting-room overlay appears, wait for the host to admit you. A connection alone does not grant canvas access.
4. Check your role in the collab roster after admission. As a viewer, watch the terminal and discuss findings with the host. As an editor, make the agreed canvas edits.
5. Ask the host for a grant to the specific terminal if the task requires typing. Verify input there before assuming another terminal is accessible.
6. If you are reconnecting, wait until the connection recovers before attempting further edits. The guest interface displays a banner explaining that edits are paused while reconnecting.

Keep one conductor and narrow the handoff

Agree on one person to direct the session. Keep reviewers as viewers when they only need to inspect Claude Code's output. Give a helper editor access and a grant to one terminal when they need to drive a focused task. State who is typing before each handoff so neither person mistakes another person's input for an agent action.

Account for reconnect limits. Terminal grants are suspended during a disconnect and can be restored if the guest returns within 120 seconds while still an editor. Output emitted during disconnection is not fully replayed; a rejoin snapshot includes capped scrollback rather than a complete replay of the missing interval. Reconfirm the terminal's current state before continuing.

The host also automatically blocks participants after the 15-minute inactivity timeout, checked on a 60-second sweep; pending joiners time out after 10 minutes. For hosted sessions, a token-server restart drops active shares because its room registry is in memory. If a session stops unexpectedly, check connection state and admission before treating the interruption as a problem with the agent.

Questions

Can an editor type into every shared terminal?

No. The host must grant that editor access to each terminal individually. Canvas editing and terminal creation permissions do not substitute for a typing grant.

Is this screen sharing?

SpeakCode replicates workspace state and streams terminal output into native guest terminal views. The host remains authoritative and runs the actual terminal processes.

What can someone see in the waiting room?

Pending guests receive no canvas content and cannot submit authorized edits or terminal input. They may still see other guests’ cursors or names.

What does internet sharing require?

You or someone on your team must run a LiveKit server plus the token service. Hosted mode is off by default, and the app ships with no backend URL. Both sides must enable hosted mode, enter both URLs under Settings → Collaboration, and verify the connection.

Pair Programming with AI Agents | SpeakCode · All guides