Tailscale Network Transport

Tailscale network transports enable Firetiger agents to connect to databases and services on your Tailscale tailnet. This is useful when your data sources are on a private network accessible via Tailscale but not reachable from the public internet.

How It Works

  1. Create a Tailscale OAuth Client for Firetiger: https://tailscale.com/docs/features/oauth-clients#register-new-nodes-using-oauth-credentials
  2. Create a Firetiger Network Transport with these OAuth Client Credentials: https://ui.cloud.firetiger.com/integrations/network-transports
  3. Create a Firetiger Connection that uses this Tailscale Network Transport
  4. The Connection’s traffic will proxy through an ephemeral tailscale node, with the tailscale tag ACLs you configure

The proxy node is ephemeral — it appears in your tailnet only while actively tunneling and is automatically cleaned up. It also joins preauthorized, so it connects immediately even on tailnets that require device approval. This relies on the OAuth client being authorized for the node’s tags (see Step 3) — preauthorization only applies to tagged nodes the client is permitted to create.

Prerequisites

  • A Tailscale account with admin access
  • The target database or service must be reachable from your tailnet (either running Tailscale directly, or behind a subnet router)
  • A service running directly on a tailnet host must listen on the tailnet interface — bind it to 0.0.0.0 (or the host’s 100.x Tailscale IP), not only 127.0.0.1/localhost, or the proxy node won’t be able to reach it

Setup

Step 1: Define an ACL Tag

Firetiger’s proxy node needs an ACL tag to identify itself on your tailnet. Define a tag in your Tailscale ACL policy.

  1. Go to Access Controls in the Tailscale admin console
  2. Add a tag to the tagOwners section:
"tagOwners": {
    "tag:firetiger": ["autogroup:admin"]
}

Step 2: Grant Network Access

In the same ACL policy, grant the tag permission to reach your database or service. Using grants:

"grants": [
    {
        "src": ["tag:firetiger"],
        "dst": ["*"],
        "ip": ["5432"]
    }
]

This allows the tag:firetiger node to connect to any machine on your tailnet on port 5432 (PostgreSQL). ip must list the port of the service you’re exposing — use the right one for the target (e.g. 5432 for Postgres, 3306 for MySQL, or your HTTP/MCP server’s port like 8080), not just 5432. Adjust dst and ip to match your security requirements:

  • Restrict dst to specific machines or tags — a tag (["tag:databases"]), a Tailscale IP or CIDR (["100.x.y.z/32"]), or a host alias defined in your policy’s hosts section. Grant dst does not accept a bare MagicDNS name like db.example.ts.net; map it to an alias in hosts first (e.g. "hosts": { "db": "100.x.y.z" }, then "dst": ["db"]).
  • Restrict ip to the specific ports your databases or services listen on

Step 3: Create an OAuth Client

Firetiger uses Tailscale OAuth client credentials to authenticate and join your tailnet.

  1. Go to Settings > Trust credentials in the Tailscale admin console (Tailscale renamed “OAuth clients” to Trust credentials)
  2. Click Generate OAuth client
  3. Configure the client:
    • Description: firetiger (or similar)
    • Tags: Select tag:firetiger
    • Scopes: Ensure auth_keys Write is included (this allows the client to generate auth keys with the selected tags)
  4. Click Generate
  5. Copy the Client ID and Client Secret — the secret is only shown once.

The OAuth client must have the tag:firetiger tag selected. Without it, the proxy cannot generate tagged auth keys and will fail with “requested tags are invalid or not permitted”.

Step 4: Create the Network Transport

Create the network transport in Firetiger using the OAuth credentials from the previous step:

  1. Navigate to https://ui.cloud.firetiger.com/integrations/network-transports
  2. Create Network Transport > Tailscale
  3. Enter your Tailscale OAuth Client connection details:
Field Required Description
oauthClientId Yes OAuth client ID from Step 3
oauthClientSecret Yes OAuth client secret from Step 3
tailnet Yes Your tailnet name (e.g., example.ts.net). Find it at Settings > General or run tailscale status --json | jq -r .MagicDNSSuffix
tags Yes ACL tags to assign to the proxy node. Must be a subset of the tags authorized on the OAuth client
hostname No Custom hostname for the proxy node in your tailnet (default: auto-generated)

Step 5: Create a Connection Using the Transport

  1. Create a Connection via https://ui.cloud.firetiger.com/integrations/connections/new
  2. Select a Connection type (e.g. Postgres, or an MCP server)
  3. Under Network Transport, select your Tailscale Network Transport
  4. Configure the Connection details

The host should be the Tailscale hostname (e.g., db-server) or Tailscale IP address (e.g., 100.x.y.z) of the machine running your database. If the database is behind a subnet router, use the private IP address that the subnet router advertises.

For HTTP-based connections such as MCP servers, the server URL points at the same Tailscale hostname/IP and the service’s port — e.g. http://my-host.example.ts.net:8080/. Both http:// and https:// server URLs work over a transport.

Click Save + Test to verify that the connection is working.

Troubleshooting

“requested tags are invalid or not permitted”

The OAuth client does not have the specified tags authorized. Go to Settings > Trust credentials, find your client, and verify it has tag:firetiger selected.

“tailnet not found”

The tailnet field has the wrong value. Find your tailnet name at Settings > General or run:

tailscale status --json | jq -r .MagicDNSSuffix

“tailnet-owned auth key must have tags set”

The network transport was created without the tags field. Update it to include tags by updating the Network Transport

Proxy node stuck waiting for approval in the Tailscale admin console

Firetiger generates preauthorized auth keys, so the ephemeral proxy node should join without manual approval even when device approval is enabled. If a node still appears unapproved, the OAuth client is likely not authorized for the node’s tags — Tailscale only honors preauthorization for tags the client is permitted to create. Verify the OAuth client has tag:firetiger (or your configured tag) selected in Settings > Trust credentials.

Connection times out after transport is established

  • Verify the database host is reachable from your tailnet (try tailscale ping <host> from another tailnet node)
  • Check that your ACL grants allow the tag:firetiger tag to reach the database host and port
  • If the database is behind a subnet router, verify the subnet routes are approved in the Tailscale admin console
This site uses Just the Docs, a documentation theme for Jekyll.