Deploy Tapicker Bridge Remotely
Use a remote Bridge when the browser, an application, or an AI agent runs on another computer. First complete Getting Started locally so you can distinguish deployment issues from pairing or Workflow issues.
A remote Bridge still routes commands to a connected Extension. It does not move the browser or the automation onto the server. Keep the browser that will execute the Workflow open and connected.
Choose Your Setup
| Setup | Bridge address seen by clients |
|---|---|
| Bridge handles TLS directly | https://bridge.example.com:9520 |
| An existing reverse proxy handles TLS | https://bridge.example.com |
Both require a trusted TLS certificate and a Bearer Token for agent/application access. The direct TLS setup below is self-contained. Use the reverse-proxy section if you already manage an HTTPS proxy.
1. Prepare the Server
You need:
- Node.js 22 or later and npm on the server.
- A DNS name pointing to it, such as
bridge.example.com. - A trusted TLS certificate and its private key for that name.
- A long random secret to use as the Bridge Bearer Token.
- Network access to the port you will publish.
Install Bridge on the server:
npm install --global @tapicker/bridge
The following terminal examples use a POSIX shell. Set the Token in the process environment, replacing the example with your own secret:
export TAPICKER_BRIDGE_TOKEN='replace-with-a-long-random-token'
Keep the Token and private key out of shared configuration files and source control. The Extension's pairing code is a separate credential; it is not the Bearer Token.
2. Start Bridge with TLS
Point to your actual certificate and key files:
tapicker bridge start \
--host 0.0.0.0 \
--port 9520 \
--tls-key /path/to/server.key \
--tls-cert /path/to/fullchain.pem
Bridge reads TAPICKER_BRIDGE_TOKEN from the environment. Non-loopback binding requires a Token and both TLS files; the CLI refuses an incomplete configuration. Make TCP port 9520 reachable by the intended clients.
Use your DNS name from other computers. A printed address containing 127.0.0.1 refers to the Bridge host itself and cannot be used to reach it remotely.
Check health using the public address:
curl https://bridge.example.com:9520/v1/health
This verifies the HTTP/TLS route, not Extension readiness. If certificate validation fails, fix the certificate name, chain, or trust setup before connecting clients.
3. Connect the Browser Extension
On the computer whose browser should run the Workflows:
- Open Tapicker and go to Settings > General.
- Enable Bridge.
- Enter
wss://bridge.example.com:9520/wsand click Connect. - Enter the current four-digit pairing code from the server's Bridge terminal.
- Wait for Connected.
Local Scan searches for a local Bridge; enter the remote address explicitly. The Extension uses pairing and its saved credential on /ws, rather than the HTTP Bearer Token.
On the Bridge host, list clients to confirm readiness:
tapicker bridge extensions
If pairing is locked, run tapicker bridge code --refresh there and use the new code. A code rotates after successful pairing, so retrieve the current one before pairing another Extension.
4. Connect an Application or Agent
These addresses share the same Bridge port:
| Caller | Address |
|---|---|
| Extension | wss://bridge.example.com:9520/ws |
| HTTP application or CLI | https://bridge.example.com:9520 |
| Direct Streamable HTTP MCP client | https://bridge.example.com:9520/mcp |
| Raw status subscription | wss://bridge.example.com:9520/v1/commands/workflow.status.watch |
HTTP and CLI
On the client computer, set TAPICKER_BRIDGE_TOKEN to the same secret, then check connected Extensions:
curl https://bridge.example.com:9520/v1/extensions \
-H "Authorization: Bearer $TAPICKER_BRIDGE_TOKEN"
For CLI access, install the CLI on that client and pass the remote base address:
tapicker workflow list --url https://bridge.example.com:9520
The CLI reads the client environment's Token automatically. Local management commands such as bridge stop and bridge code must be run on the Bridge host; --url does not turn them into remote administration commands.
Direct MCP
In the agent, select Streamable HTTP, use https://bridge.example.com:9520/mcp, and configure the header Authorization: Bearer YOUR_TOKEN. No local tapicker mcp process is needed.
For an agent that supports only stdio, install the CLI on the agent's computer and configure:
{
"mcpServers": {
"tapicker": {
"command": "tapicker",
"args": ["mcp", "--url", "https://bridge.example.com:9520"],
"env": { "TAPICKER_BRIDGE_TOKEN": "YOUR_TOKEN" }
}
}
}
This configuration is stdio because the agent launches a local adapter. Use secret storage when your agent provides it. See MCP for the tool verification flow and URL tolerance rules.
Use an Existing Reverse Proxy
To terminate TLS at a reverse proxy on the same server, keep Bridge bound to loopback and set a fixed internal port. With the Token environment variable still set, start:
tapicker bridge start --host 127.0.0.1 --port 9520
Configure the proxy's HTTPS site at https://bridge.example.com to forward to http://127.0.0.1:9520. Publish the Bridge at the domain root; the CLI/stdio adapter does not support an arbitrary path prefix such as /tapicker.
Forward the paths unchanged:
| Path | Proxy requirement |
|---|---|
/v1/... | Forward HTTP methods, bodies, and the Authorization header |
/mcp | Preserve MCP headers and streaming responses; disable response buffering |
/ws | Support WebSocket upgrade for the Extension |
/v1/commands/workflow.status.watch | Support WebSocket upgrade and the Authorization header |
For a loopback-bound Bridge, /mcp validates the upstream Host header. Set that header to the internal target, for example Host: 127.0.0.1:9520, when proxying to it. Preserve headers such as Mcp-Session-Id, MCP-Protocol-Version, Accept, and Last-Event-ID as well as Authorization. Set timeouts appropriate for long-running streams.
Clients then use https://bridge.example.com and wss://bridge.example.com, without the internal 9520 port. Pair the Extension with wss://bridge.example.com/ws and configure direct MCP with https://bridge.example.com/mcp.
Verify health, Extension pairing, an authenticated Workflow list, and an MCP tool call through the public address. A working health endpoint alone does not verify WebSocket upgrades or MCP streaming.
Keep the Service Available
Once the foreground setup works, run the same start command with --daemon or use your server's process supervisor. Keep the working Token, TLS paths, port, and data directory in that service's configuration. Restart the service when its Token or TLS files change.
Keep the Bridge data directory across service restarts so Extensions can reconnect without pairing again. It defaults to ~/.tapicker. Use the same operating-system user and data directory for local management commands.
To stop the service on the server:
tapicker bridge stop
Use --data-dir here if the service uses a custom directory. Stopping Bridge disconnects clients; it is not a substitute for stopping a Workflow in the browser.
Access and Troubleshooting
The Bearer Token protects commands, /v1/extensions, /mcp, and status subscriptions. /v1/health, /v1/discovery, and /v1/capabilities are public. Pairing protects the Extension's separate /ws connection. A token holder can issue supported commands to accessible Extensions; Bridge does not add a separate Tapicker account or role system.
CORS defaults to *. If browser applications call the API, restrict their origins with bridge start --cors-origin https://app.example.com or a comma-separated allowlist. CORS controls browser requests; it does not replace the Token or Extension pairing.
| Symptom | What to check |
|---|---|
| Connection refused or timed out | Public hostname, published port, firewall, proxy route, and service process |
| TLS failure | Matching hostname, full certificate chain, and trusted certificate |
Unauthorized | The client sends the same Token used by Bridge |
| Extension cannot connect | Use wss://.../ws; check WebSocket upgrades and the current pairing code |
| HTTP works but MCP fails | MCP URL, internal Host header for a loopback upstream, preserved headers, and streaming |
ExtensionUnavailable | Keep the browser open and check Extension readiness |
| Local management cannot find Bridge | Run it on the host with the service's user and data directory |
For a daemon startup failure, check bridge.log in the Bridge data directory.
Continue with CLI, HTTP, or MCP for the commands your clients will use.