Share a Session

A taiku session is a live, encrypted terminal stream that people join through a URL. This guide covers how sessions are created, how sharing works, how reader, writer, and admin access differ, and what happens when connections drop.

Creating a session

Run taiku in your terminal to start a session:

taiku

The CLI authenticates with the server, generates a unique encryption key, and begins streaming your terminal output. You will see something like this:

taiku v0.4.3

session: https://taiku.live/s/abc1234xyz#encKeyHere...
  1 terminal window (Up/Down to switch)
  Ctrl-C to exit

That URL is what a collaborator needs to decrypt the session. They paste it into any modern browser and join live. Depending on your viewer-auth setting and plan, the server may also require them to be logged in before the WebSocket connects.

Behind the scenes, the CLI opens a gRPC connection to the taiku server and begins forwarding terminal bytes in both directions. The server holds session state in memory (and optionally snapshots it to Redis for multi-region routing), and it authenticates clients using a verifier derived from the session secret, but it does not receive the raw fragment secret itself.

The session secret and URL fragment

The session secret lives in the URL fragment (after #). Browsers do not send fragments in the normal HTTP request, so the server does not receive the raw secret. If you share the URL through a channel that strips fragments, the browser will not be able to decrypt the session.

For the full encryption model, including key derivation, cipher details, and the threat model, see Security.

Sharing and joining

Send the full URL to anyone you want to collaborate with. They open it in their browser and use the fragment to decrypt the session. There is no waiting room or manual approval step by default. The URL is the main credential, though viewer OAuth may also be required depending on how the session was created.

This makes taiku especially fast for the most common sharing scenarios:

Pair debugging. You hit a confusing error, paste the URL in Slack, and your teammate is looking at your terminal within seconds. They can type commands, scroll history, and see exactly what you see.

Live demos. Share the URL in a meeting chat. Attendees watch your terminal in real time. If you want them to interact, they can. If you want view-only access, use --enable-readers (covered below).

Teaching. A student shares their session with an instructor. The instructor can watch, take over when needed, or open a peek view to monitor without interrupting.

Support. A user shares their terminal with a support engineer. The engineer sees the exact environment, the exact error, the exact state, without asking "what does it say when you run...".

Read-only vs. write access

By default, every participant who joins a session can type into terminals. This is the right default for pair programming and small-team collaboration, but sometimes you want viewers who can watch without typing.

To create separate read-only and write links, start the session with the --enable-readers flag:

taiku --enable-readers

The CLI will print reader and writer URLs, and in the default app flow it may also print an admin URL:

taiku v0.4.3

reader: https://taiku.live/s/abc1234xyz#sessionSecret...
writer: https://taiku.live/s/abc1234xyz#sessionSecret...,writePassword...
admin:  https://taiku.live/s/abc1234xyz#sessionSecret...,adminPassword...
  1 terminal window (Up/Down to switch)
  Ctrl-C to exit

The write URL works like the default URL plus an extra write password. Anyone with it can type into terminals, create new shells, and interact fully.

The read-only URL gives viewers a live view of the same encrypted session, with the ability to scroll history and use the peek panel, but no ability to send keystrokes to any terminal. Read-only viewers can still use the chat sidebar, see other participants, and browse the workspace layout.

A few concrete scenarios where --enable-readers makes sense:

• Conference talks. Share the read-only link with the audience. They follow along on their own screens without anyone accidentally typing into your demo.
• Classroom settings. Students get the read-only link. The instructor and TAs get the write link. Students can watch the instructor's terminal and ask questions in chat.
• Incident response. The on-call engineer shares a write link with the response team and a read-only link in the broader incident channel for visibility.

Session lifetime and reconnection

A taiku session stays alive as long as the CLI process is running. The server holds state for the session and routes traffic between the CLI and connected browsers.

If the CLI disconnects, whether because of a laptop sleep, a brief network interruption, or an accidental terminal close, the server does not immediately destroy the session. It holds the session state for a 5-minute reconnection window. If the CLI reconnects within that window, the session resumes seamlessly. Browsers that were connected will see the terminal come back to life without needing to refresh.

After the 5-minute window expires without a reconnection, the server destroys the session. Connected browsers will see a disconnection notice.

What this means in practice:

• Laptop sleep. Close your laptop lid, reopen it three minutes later. The session picks up where it left off. Browsers that stayed open will automatically reconnect.
• Network blip. A brief Wi-Fi dropout of a few seconds is invisible to participants. The CLI automatically reconnects.
• Process exit. If the CLI process is killed (Ctrl-C, kill, crash), the 5-minute window still applies. You can restart taiku and it will attempt to reconnect to the same session if it is still alive.
• Beyond 5 minutes. If you are offline for more than 5 minutes, the session is gone. Start a new one.

The 5-minute window is a deliberate tradeoff. It is long enough to survive common disruptions but short enough that abandoned sessions do not consume server resources indefinitely.

Viewer authentication

By default, connecting to a session requires both:

• the session secret embedded in the URL fragment, which lets the browser derive the terminal encryption key
• viewer OAuth, when required by the session and plan

The fragment is still the thing that unlocks the encrypted terminal stream. The server-side viewer-auth check is a separate gate before the WebSocket is opened.

For Pro users, taiku offers an additional option: --no-viewer-auth. This disables the OAuth viewer-auth requirement, allowing anyone with the session URL to connect without first signing in:

taiku --no-viewer-auth

This is useful for scenarios where you want easy viewing, such as a public demo or a team dashboard session. It does not remove the URL fragment requirement: viewers still need the session secret to decrypt the terminal stream. Write access still requires the full write URL when --enable-readers is active.

On the Free tier, viewer authentication is always enabled. This ensures that sessions are private by default and that sharing is always an intentional act.

Desktop vs. CLI-only mode

taiku has two modes for the host: the desktop app and CLI-only mode. Both create the same kind of session; the difference is in how the host interacts with it.

Desktop app

The desktop app wraps the CLI in a native window using Tauri. It is the default when you run taiku on a machine where the desktop app is installed. The app provides:

• A persistent session attached to a native window, so it does not get lost in terminal tabs.
• A dashboard for managing multiple sessions and devices.
• Native notifications for collaboration events.
• The ability to launch sessions from the GUI rather than the command line.

The desktop app is best when you want the machine to stay reachable over time, when you manage multiple sessions, or when you prefer a dedicated window for terminal sharing.

CLI-only mode

If you want to skip the desktop app and run everything in your terminal, use the --no-app flag:

taiku --no-app

This keeps the session entirely in your terminal. The CLI prints the URL, streams terminal data, and exits when you press Ctrl-C. There is no native window, no dashboard, no tray icon.

CLI-only mode is best for:

• Headless servers. SSH into a remote machine, run taiku --no-app, and share the URL. No GUI needed.
• Temporary sessions. You just want to show someone your terminal for five minutes. CLI-only mode has zero overhead.
• Scripting. Embed taiku --no-app in scripts or CI pipelines where a desktop app would be inappropriate.

Putting it together

A typical workflow might look like this:

# Start a session with read-only viewers enabled
taiku --enable-readers

# Output:
# reader: https://taiku.live/s/abc1234xyz#sessionSecret...
# writer: https://taiku.live/s/abc1234xyz#sessionSecret...,writePassword...
# admin:  https://taiku.live/s/abc1234xyz#sessionSecret...,adminPassword...

# Send the write URL to your pair programmer
# Send the read URL to the rest of the team

# Work together in real time
# When done, Ctrl-C to end the session

The session is live for as long as the CLI runs. Everyone who has the URL is in the same room, seeing the same terminals, with the access level you chose. No accounts, no installation, no configuration on the viewer side.

For what happens once multiple people are in a session, continue to Collaboration.