Tailscale connections
Connect your tailnet once in workspace settings, then let runners and sandboxes join it without auth keys.
A Tailscale connection lets runners and sandboxes join your tailnet as tagged devices. You add it once under Settings > Networking. After that, Luxor Agent Cloud asks Tailscale for a short-lived auth key each time a workload starts, using OpenID Connect. It stores no Tailscale auth key or OAuth secret.
With a connection in place you can:
- make it the default for new sandboxes, new GitHub runner jobs, or both
- add a dedicated runner label, so only jobs that use that label join your tailnet
- attach it to one sandbox from the CLI
This video sets up two connections.
company-staging becomes the default for sandboxes and for runner jobs in two repositories.
company-prod gets a dedicated runner label that only protected-branch jobs in acme/infra can use.
How it works
- A sandbox or runner job starts.
- We sign an OpenID Connect token whose subject names your workspace, the connection, and the session.
- Tailscale checks the token against the trust credential you created and returns an API token limited to its scopes and tags.
- We use that token to create an auth key, and the workload joins your tailnet with your tags.
- When the workload ends, we remove the device.
Your tailnet policy decides what those tagged devices can reach. Write grants or ACLs for the tags you allow, the same way you would for any other tagged device.
Add a connection
Before you start, make sure every tag you plan to use is listed under tagOwners in your tailnet policy file.
Open Settings > Networking and click Add connection.
Under Set up trust, enter a Connection name and the Allowed tags.
The name uses lowercase letters, numbers, and dashes, and starts with a letter, for example company-staging.
Tags are comma-separated, such as tag:ci, tag:staging, with up to 16 per connection.
Keep the Add Tailscale connection dialog open and click Open Tailscale to go to the Trust credentials page. Click Credential, choose OpenID Connect, and fill it in with the values from the dialog:
Click a value in the dialog to copy it. Then click Generate credential in Tailscale and copy the Client ID and Audience.
The connection ID in the subject is created when the dialog opens. If you close the dialog and start again, the subject changes, and you need to update the trust credential to match.
Back in the dialog, click Continue, paste the Client ID and Audience, and click Save connection.
The connection appears in the Tailscale Connections table as Enabled. The Default for column stays empty until you set a default.
Test a connection
Click Test on the connection's row, then Run test. Luxor Agent Cloud joins your tailnet with a short-lived device and removes it when the test finishes.
To check that a service is reachable too, select Also check a private endpoint and enter its URL, for example https://internal-api.example.ts.net/health.
The test then checks DNS and HTTP access to that URL from inside your tailnet.
Set workspace defaults
The Tailscale Defaults card has one row for sandboxes and one for GitHub runners. Each row shows Not set until you pick a connection. Click Set default, choose a connection, and click Save default. To clear a default, click Change and choose None.
The two defaults are independent, so sandboxes and runners can use different connections.
Sandboxes
Every new sandbox in the workspace joins the default connection, whether you create it with the CLI, an SDK, or a template in the dashboard. Create waits until the sandbox's device is online on your tailnet.
To skip the default for one sandbox, use --no-tailnet with the luxor CLI 2.8.0 or later:
luxor sandbox create --no-tailnetWhen you launch a template from the dashboard, the Tailscale connection field offers the workspace default, No Tailscale connection, or any other enabled connection.
GitHub runners
The runner default applies to Linux jobs on standard labels, such as luxor-ubuntu-medium-4c-8g, and works per repository.
When you set it, you choose:
- Default runner repository allowlist: the repositories whose jobs join the connection. Only repositories connected to the workspace are listed. If none appear, connect GitHub on the Runners page first.
- Include pull requests from forks: off by default.
Jobs from branches in an allowlisted repository join your tailnet, including pull requests from that repository. Pull requests from forks join only when you select Include pull requests from forks. Every other job still runs, without Tailscale: jobs from repositories outside the allowlist, and fork pull requests while the checkbox is off. Luxor Agent Cloud removes the tailnet from a fork pull request's runner before any step runs. The job's logs page then shows Job access excludes this job, so it runs without Tailscale. For the runner default, "job access" in that message means its repository allowlist and fork pull request checkbox.
Forks can reach your tailnet when included
With Include pull requests from forks selected, anyone who can open a pull request in an allowlisted repository can reach whatever your tags allow. For branch or event rules, use a dedicated runner with a job access level instead.
Add a dedicated runner
A dedicated runner is a runner label tied to one connection. Only jobs that ask for that label join your tailnet, so the rest of your CI keeps running as before.
Luxor Agent Cloud creates a label that starts with tenki-tailnet-.
You can use it as shown, or with the luxor- prefix (luxor-tailnet-<id>).
Click the label in the table to see a workflow example and the runners that started on it recently.
Use the label in runs-on:
jobs:
integration:
runs-on: luxor-tailnet-<id>
steps:
- uses: actions/checkout@v4
- run: curl --fail https://internal-api.example.ts.net/healthThe job joins your tailnet before any step runs. You don't need a Tailscale step or a GitHub secret in the workflow.
Each entry under Recent runners shows the runner's device name, Tailscale IP, and state: pending, joining, online, detached, or error.
detached means the job finished and Luxor Agent Cloud removed the device, so the entry no longer shows a Tailscale IP.
Job access denied means the job's repository, branch, or event didn't match the policy.
To stop new jobs on a label, open Edit dedicated runner from the row's menu and select Disable new jobs on this label.
Job access
Dedicated runners use one of three job access levels. All three apply only to repositories in the allowlist. The runner default has no job access setting; it admits same-repository jobs, and fork pull requests only when you include them.
Choose All jobs, including fork PRs only for repositories where you trust everyone who can open a pull request. Anyone who can run a job on the label can reach whatever your tags allow on your tailnet.
Jobs that don't match job access
A dedicated runner never starts a runner for a job its job access doesn't allow.
This also applies to jobs from repositories outside the allowlist, and to new jobs on a disabled label.
GitHub keeps the job queued, showing "Waiting for a runner to pick up this job", until the job fails at the 24-hour queue limit for self-hosted runners.
With Protected branches only, for example, a push to an unprotected branch and every pull request stay queued.
The job doesn't show up under Recent runners, because no runner started.
To run it, change the job access, protect the branch, or move the workflow to a standard label. Cancel the queued run in GitHub if you don't want to wait for the timeout.
The runner default behaves differently: a job it doesn't allow still runs, without Tailscale.
Use a connection with one sandbox
Click a connection's name, or choose Use connection from its menu, to see its ID and a ready-to-copy command:
luxor sandbox create --tailnet-profile-id <connection-id>This needs the luxor CLI 2.8.0 or later.
It works whether or not the connection is a default, and you don't need an auth key.
Add --tailnet-wait-for-online to return only after the device is online; without it, create can return while the device is still joining.
Connections from your tailnet into the sandbox reach only ports you expose with --tailnet-expose-port, for example --tailnet-expose-port 8080.
To attach a sandbox with your own Tailscale auth key instead, see Tailscale for sandboxes.
Edit or disable a connection
Use the menu at the end of a connection's row.
- Edit connection changes the name, tags, client ID, or audience. Changes apply to new workloads only. If you change the tags, update the trust credential in Tailscale to match.
- Disable connection stops new workloads from using it. Sandboxes and jobs that are already running keep their connection.
A disabled connection that is still a default makes new sandboxes, or new runner jobs on standard labels, fail. The Tailscale Defaults card warns about this. Change or clear the default when you disable its connection.