Tailscale

Connect a Tailscale tailnet so Autosana web runners can reach apps that aren’t publicly accessible, including staging behind an internal load balancer, split-DNS hostnames, and services behind subnet routers.

​

How it works

The private network is connected once per workspace and applies to every environment in it, including environments created later.

1. Preview: a workspace admin enters a temporary Tailscale API access token, the exact Tailnet ID, and structured targets. Autosana reads the current tailnet configuration and shows the exact policy additions it proposes. Preview does not change Tailscale.
2. Apply: after a separate confirmation, Autosana adds the reviewed grants and creates a generated runner identity. The temporary token is discarded and is never stored.
3. Check routing: Autosana joins with a short-lived key and checks Tailscale DNS and route selection. This does not fetch your application or return application response content.
4. Run: each web flow run joins the tailnet only for the browser session and leaves when the run ends.

The dashboard shows Autosana-managed Tailscale access: the additions Autosana owns, not your tailnet’s total effective access. Other policy you manage can grant additional access.

​

Choose a target type

Enter each target as a logical hostname or URL, optional route CIDRs, protocol, and port. The preview shows the canonical origin that will be stored. Logical targets derive TCP and the destination port from the hostname or URL. Protocol and port are entered separately only for route-only bindings.

​

App Connector hostname

For a hostname already covered by a Tailscale App Connector, Autosana dynamically reuses that connector. Preview shows its name, configured domains and routes, tags, TCP ports, and device availability. DNS address changes behind the hostname do not require rewriting the Autosana-managed grant.

​

Explicit private route

For a private hostname that is not covered by an App Connector, provide the exact application CIDR or CIDRs routed through your tailnet. Autosana preserves the logical hostname for test traffic while authorizing only those explicit routed networks at the selected port. Split-DNS targets also need their private resolvers to be reachable. Preview lists every exact resolver dependency separately as an IPv4 /32 or IPv6 /128, with TCP and UDP port 53, the matching DNS suffix, and its route source. Autosana does not authorize an entire DNS subnet just because one resolver is inside it.

​

Route-only binding

Leave the logical hostname empty only when you want a route-only binding. You must provide at least one route CIDR, a protocol, and a port.

​

Set up an App Connector

Complete this setup in Tailscale before Preview when the application hostname should route through a stable connector, such as a public staging site that allowlists only the connector’s public IP. You need a Tailscale Owner, Admin, or Network admin and a Linux connector device that is already joined to the tailnet, has IP forwarding enabled, and has a public IP address.

1. Choose a dedicated connector tag, such as tag:app-connector-autosana. This tag identifies your connector device; it is separate from the generated tag:autosana-… runner tag that Autosana creates during Apply. Treat tag:autosana and the tag:autosana-* prefix as Autosana-managed names.
2. In Tailscale Access controls, merge the connector tag owner and route auto-approvals into your existing policy. Do not create duplicate top-level sections.
   {
     "tagOwners": {
       "tag:app-connector-autosana": ["autogroup:admin"]
     },
     "autoApprovers": {
       "routes": {
         "0.0.0.0/0": ["tag:app-connector-autosana"],
         "::/0": ["tag:app-connector-autosana"]
       }
     }
   }
   
   These default-route entries let any device carrying the connector tag automatically approve the routes it advertises. Keep tagOwners tightly restricted and assign the tag only to the intended connector devices. The approvals do not grant Autosana access by themselves; Autosana adds separate runner-specific grants during Apply.
3. On the Linux connector device, advertise it with the same tag:
   sudo tailscale up --advertise-connector --advertise-tags=tag:app-connector-autosana
   
4. In Tailscale, open Apps, select Add an app, and enter:
   • Name: any unique admin-console name, such as autosana-app.
   • Target: Custom, unless the application is one of Tailscale’s preset apps.
   • Domains: the exact hostname or hostnames Autosana will test, such as staging.example.com. Do not include https://, paths, query strings, or ports. Use a wildcard only when every matching subdomain should use this connector.
   • Connectors: select tag:app-connector-autosana, or the dedicated connector tag you chose in step 1.
5. Save the app and confirm Tailscale shows the connector as active.
6. In Autosana, enter the same application hostname as the logical target. Preview must classify it as App Connector hostname and show the expected connector name, tag, domains, and an online connector device before you Apply.

Autosana adds only the reviewed runner-specific grants and its generated runner tag. It does not provision the Linux connector, configure its domains, or change the connector tag’s route auto-approvals. See Tailscale’s App Connector setup guide for device and policy details.

​

Preview and apply

1. Create a temporary Tailscale API access token.
2. In Autosana, go to Settings → Integrations → Autosana-managed Tailscale access and select Connect.
3. Enter the Tailnet ID shown on Tailscale’s General page and add the structured targets.
4. Select Preview changes.
5. Review the exact managed grants, App Connector details, application CIDRs, private-DNS dependencies, and warnings.
6. If Autosana finds legacy policy candidates, choose each one you want removed. They are never selected or deleted automatically.
7. Select Review apply, then use the separate Apply changes confirmation.
8. Revoke the temporary API token in Tailscale after Apply completes.

If policy, routes, DNS, or the current installation changes after Preview, Apply fails safely. Create a fresh preview instead of widening access or silently using the legacy setup. Use Upgrade/Reconnect on an older connection or Reconnect on a current connection to preview changed targets without disconnecting first. The existing generation stays active until the replacement is published.

​

Stored credential authority

Autosana stores one encrypted Tailscale OAuth credential with the auth_keys scope and its generated runner tag. The tag limits which tag newly created auth keys can receive. The auth_keys scope is not mint-only: it can also read and delete machine auth keys through Tailscale’s key API. It cannot administer tailnet policy, DNS, OAuth clients, or devices. Runtime keys are short-lived, single-use, ephemeral, and tagged.

​

Disconnect and cleanup

Disconnect is tokenless. Before sending the request, Autosana asks you to confirm that it will immediately disable the local binding while Tailscale policy and the OAuth client may remain. Without temporary administrative authority, those remote resources may not be removable at that moment, and completing cleanup later can require a new full admin token. If remote cleanup is deferred, the dashboard reports Remote cleanup required and lists backend-approved non-secret identifiers, resource status, and cleanup counts for follow-up. A later token-bearing setup can reconcile known resources, or an administrator can use those identifiers to remove them in Tailscale. A successful local disconnect does not promise that every remote resource was deleted.

​

Troubleshooting routing

• No primary route covers an application CIDR — advertise and approve the exact subnet route in Tailscale, then run Check routing again.
• A private DNS resolver is unrouted — make the exact resolver /32 or /128 reachable through an approved primary route. Do not broaden the application CIDRs to compensate.
• An App Connector is unavailable — confirm that a uniquely matching connector is configured, tagged, online, and advertising the expected domain or route.
• Routing configured but a test still fails — routing readiness does not connect to the destination. Run an Autosana test to exercise the application data plane, then troubleshoot the application, TLS, or authentication separately.
• Preview or Apply reports a conflict — the plan became stale or another private-network operation is active. Wait for the current operation, then create a new preview.