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

SetupBridge address seen by clients
Bridge handles TLS directlyhttps://bridge.example.com:9520
An existing reverse proxy handles TLShttps://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:

  1. Open Tapicker and go to Settings > General.
  2. Enable Bridge.
  3. Enter wss://bridge.example.com:9520/ws and click Connect.
  4. Enter the current four-digit pairing code from the server's Bridge terminal.
  5. 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:

CallerAddress
Extensionwss://bridge.example.com:9520/ws
HTTP application or CLIhttps://bridge.example.com:9520
Direct Streamable HTTP MCP clienthttps://bridge.example.com:9520/mcp
Raw status subscriptionwss://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:

PathProxy requirement
/v1/...Forward HTTP methods, bodies, and the Authorization header
/mcpPreserve MCP headers and streaming responses; disable response buffering
/wsSupport WebSocket upgrade for the Extension
/v1/commands/workflow.status.watchSupport 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.

SymptomWhat to check
Connection refused or timed outPublic hostname, published port, firewall, proxy route, and service process
TLS failureMatching hostname, full certificate chain, and trusted certificate
UnauthorizedThe client sends the same Token used by Bridge
Extension cannot connectUse wss://.../ws; check WebSocket upgrades and the current pairing code
HTTP works but MCP failsMCP URL, internal Host header for a loopback upstream, preserved headers, and streaming
ExtensionUnavailableKeep the browser open and check Extension readiness
Local management cannot find BridgeRun 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.