SESSIONS & CONTROL
Reach localhost from a remote browser
Chrome runs on your server, so localhost inside the browser means the server. A loopback tunnel is the one exception, and it is off by default.
Why localhost points at the server
Tallylamp's Chrome runs inside your deployment. When a page redirects to http://localhost:3000/callback, Chrome resolves that address inside the container. Consent succeeds, but the app waiting on your laptop never gets the code.
The egress proxy also refuses private addresses, because a browser pointed at hostile sites should not be able to probe your network. A tunnel reopens one of those addresses for one browser. The rest stay refused.
Open a tunnel
Only the browser's owner or an administrator can open a tunnel. An administrator token needs nothing else. An agent needs the non-default browser:tunnel scope, which an administrator grants under Agents, Permissions or with PATCH /api/v1/agents/:id, and the agent must own the browser. Either way, nothing is reachable until a command is running on the machine that has the port, because only that machine can reach it.
Get the command
Either use the command below, with TALLYLAMP_TOKEN set to an agent or administrator token and TALLYLAMP_URL set to your deployment, or let an agent with the scope call tallylamp_open_tunnel. The tool returns a connect token, shown only once, and the exact command to run. That form uses TALLYLAMP_TUNNEL_TOKEN instead of an agent token and runs the binding the agent already created.
Run it on the machine that has the port
You need Node 22 or newer and a clone of the Tallylamp repository on that machine. The client has no dependencies to install. Leave it running for as long as the browser needs the address.
Check the dashboard
The browser's page lists open tunnels and whether anything is connected. A tunnel that is bound but not connected answers 502 in the browser: the command never ran, or the client exited.
TALLYLAMP_TOKEN=tl_ag_… TALLYLAMP_URL=https://YOUR_HOST \
node bin/tallylamp.mjs tunnel 3000 --host localhost --browser my-browserTunnel rules
| Rule | What it means |
|---|---|
| One binding, one host and port | Each binding ties one browser to one host and port, fixed when the tunnel opens. Chrome cannot pick a different destination. A browser can hold up to four bindings at once by default. |
| Private addresses only | Loopback, private IPv4 and IPv6 ranges, link-local, .local and .internal names are accepted. A public hostname is refused, because binding one would divert that browser's traffic for a real site. |
| Outbound from your machine | Your machine opens a WebSocket to the server. Nothing new listens, and there is no public URL for strangers to find. |
| Expires and can be revoked | One hour by default. Pass --ttl SECONDS, or ttlSec from the agent, for up to twelve hours. Closing a tunnel cuts live connections. |
| Closed by lending | Lending the browser closes its tunnels, including when a lendable browser is granted automatically after it goes idle. A borrower cannot open or list them. |
While a tunnel is open, any page in that browser can reach the bound address. Close it when the job is done. Ctrl-C ends the client and revokes a binding the client opened. A binding an agent opened stays until it expires, the agent calls tallylamp_close_tunnel, or you choose Close on the browser's dashboard page.
Docs behind this guide
Based on Tallylamp's documented behaviour. See the source for API details and release-specific settings.