HTTP Tunnels

HTTP tunnels let you expose a local web server through your taiku session. The most common use case is sharing a live preview of an application you are developing: you start a dev server on localhost:3000, publish that port through taiku, and anyone in the session can interact with the running app in a tiled pane right next to the terminal that drives it.

Starting a tunnel

Pass the --tunnel flag with one or more ports when you launch a session:

taiku --tunnel 3000

You can publish multiple ports at once by separating them with commas:

taiku --tunnel 3000,8080

When the session starts, taiku prints the session URL followed by a public tunnel URL for each declared port:

  taiku v2.0
  Session URL: https://taiku.live/s/abc123#e8Xk...

  Tunnels:
    :3000  https://taiku.live/t/abc123/p/3000/
    :8080  https://taiku.live/t/abc123/p/8080/

Those URLs are publicly reachable for the lifetime of the session. Anyone with the link can interact with the local service, and session participants can open the tunnels as inline previews or full browser tabs.

How proxying works

Tunnel requests travel a full round trip through the taiku server and back to your machine. The flow looks like this:

1. A browser sends an HTTP request to https://taiku.live/t/{session}/p/{port}/path.
2. The taiku server identifies the session and forwards the request metadata (method, headers, body) over gRPC to the CLI client that owns the session.
3. The CLI makes a local HTTP request to http://127.0.0.1:{port}/path, rewriting the Host header to 127.0.0.1:{port} and stripping hop-by-hop headers like Connection and Transfer-Encoding.
4. The local server responds. The CLI streams the response body back to the server in 64 KB chunks.
5. The server reassembles the response and delivers it to the original browser request.

Because the proxy is HTTP-level (not TCP-level), it handles compressed responses, chunked transfer, and redirects transparently. The server applies a 30-second timeout per request and a 10 MB limit on request bodies.

Service Worker installation

On first navigation to a tunnel URL, the server returns a small bootstrap page instead of proxying the request. This page installs a Service Worker scoped to the tunnel's base path (/t/{session}/p/{port}/). The Service Worker rewrites all subsequent requests so that relative paths like /style.css resolve to /t/{session}/p/{port}/style.css, and it adds an X-Tunnel-SW: 1 header so the server knows to proxy rather than serve the bootstrap page again.

Once the Service Worker is active the page reloads automatically, and from that point on the tunneled app behaves as though it were hosted directly. Asset paths, relative links, and client-side routing all work without any content rewriting on the server side.

This approach means tunnels require a browser with Service Worker support. The bootstrap page detects this and shows a message if the feature is missing.

Port approval

Not every port request is automatically honored. Taiku uses a three-tier approval model that balances convenience with control.

Declared ports are the ports you pass to --tunnel when starting the session. These are always available from the start.

Auto-approved mode is enabled with the --open-tunnel flag:

taiku --tunnel 3000 --open-tunnel

In this mode, any session participant can request additional ports at any time, and the CLI automatically approves them. The CLI prints a green notice when this happens:

  [tunnel] Port 4200 requested by "alice". Auto-approved.

Tunnel admin approval is the middle ground. If a session has an admin link, anyone with that link can approve port requests without needing the --open-tunnel flag. When a tunnel admin approves a port, the CLI prints:

  [tunnel] Port 4200 requested by "alice". Approved by tunnel admin.

Default deny applies when neither --open-tunnel is set nor a tunnel admin is present. The CLI rejects the request and prints a warning:

  [tunnel] "alice" wants to expose port 4200. Denied - no admin present (use --open-tunnel to auto-approve).

This model lets you share sessions with collaborators while keeping port exposure intentional. For a solo development workflow, --open-tunnel removes friction entirely.

Viewing tunnels

Once a port is tunneled, there are three ways to interact with it:

Inline previews display the tunneled app in a small embedded pane within the session interface. This is useful for quick checks: you can see the app rendering while your terminal is still visible.

Tiled panes are full workspace tiles, just like terminals. You can split your workspace so a tunnel pane sits next to the terminal running your dev server. Each tunnel tile has a minimal browser chrome with back, forward, reload, and open-in-tab buttons. Tunnel tiles can be resized, rearranged, and renamed like any other tile in the workspace.

Full browser tabs open the tunnel URL in a new browser tab, giving you the full browser experience with devtools, address bar, and native navigation.

Tunnel tiles include refresh and hard refresh controls in their titlebar. A normal refresh reloads the page while preserving Service Worker caches, which is fast and works for most code changes. A hard refresh bypasses the Service Worker and reloads everything from the tunnel origin. Use this when you've changed static assets, updated build artifacts, or suspect a stale cache is showing outdated content.

For development workflows, tiled panes are usually the best fit. You get a side- by-side view of your code running in the terminal and its output rendering in the browser, all within a single session that collaborators can see simultaneously.

When to use managed vs. open mode

Managed mode (the default) is appropriate when multiple people are collaborating in a session and you want control over which ports are exposed. Only declared ports and admin-approved ports become tunnels. This is the safer default for teaching, pair programming, or any situation where you want to review what gets published.

Open mode (--open-tunnel) is appropriate when the session is essentially a shared preview environment. If you are demoing an application, running a workshop where participants need to spin up their own services, or simply working solo and want the fastest path to a live preview, open mode removes the approval step entirely.

Combining tunnels with workspaces

Tunnels become especially useful when combined with taiku's workspace tiling. A typical development setup might look like this:

taiku --tunnel 3000,5173 --open-tunnel

Inside the session, you split the workspace into three panes: a terminal running your backend server on port 3000, a terminal running your frontend dev server on port 5173, and a tunnel tile showing the frontend preview. Changes you make in either terminal are immediately visible in the tunnel pane.

Because workspaces are per-user, each collaborator can arrange their own layout. One person might tile the two tunnels side by side for a visual comparison, while another keeps a single terminal maximized with the tunnel in a small corner.

For more on workspace layouts, see the workspaces guide.