> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niteshift.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tailscale

> Join each task to your tailnet as an ephemeral, tagged node without storing an auth key.

Niteshift joins each task to your tailnet using Tailscale workload identity federation, so no auth
key or OAuth client secret is stored. Each task is an ephemeral, tagged node named
`niteshift-<task-id>`, lowercased with `_` replaced by `-`. Every start and resume registers a fresh node, and Tailscale removes the old
one.

> [!TIP]
>
> Ask the agent in a task to connect Tailscale. It writes the configuration, walks you through the
> Tailscale-side setup below, and verifies access. See the [quick
> start](https://docs.niteshift.dev/integrations/overview.md#quick-start).

Declare the federated identity's client ID and the tags its nodes advertise in the environment's
committed `settings.yaml`. Both keys are required, `tags` is a non-empty list of `tag:<name>`
values, and no other keys are accepted:

```yaml settings.yaml theme={"dark"}
version: 1
integrations:
  tailscale:
    clientId: <tailscale-client-id>
    tags: [tag:niteshift]
```

Niteshift derives the audience as `api.tailscale.com/<clientId>`, so there is no audience setting.
The issuer and subject don't depend on the audience. Run this in the Niteshift terminal tab to see
them before you have a client ID:

```bash theme={"dark"}
ns oidc-token --inspect --audience 'api.tailscale.com/placeholder'
```

In the Tailscale admin console:

1. Add each tag to `tagOwners` in the [policy file](https://console.tailscale.com/admin/acls/file),
   and grant the tags only the access tasks need.
2. In [Trust credentials](https://console.tailscale.com/admin/settings/trust-credentials), add an
   **OpenID Connect** credential with **Custom issuer**. Enter the inspected `iss` as **Issuer URL**
   and the entire inspected `sub` as **Subject**. Leave **Audience** blank and remove the empty
   **Custom claims** row; **Continue** stays disabled until you do.
3. On the **Scopes** page, choose **Custom scopes**, then **Keys** > **Auth Keys** > **Write**, and
   select the tags from `settings.yaml`.
4. Copy the generated **Client ID** into `clientId`.

The `sub` has the form `org:<org_id>:environment:<environment_id>`. A subject ending in `*` trusts
every environment in the organization; use the exact value. Copying an environment gives the copy a
new `sub`. Create a separate trust credential for the copy and put its client ID in the copy's
`settings.yaml`, so the original keeps working.

New tasks join automatically. In a running task, run `ns tailscale configure` in the Niteshift
terminal tab to join or leave the tailnet according to the current settings. If an existing task
still doesn't join, start a new task; tasks created before Tailscale support can't join.

Each task appears in [Machines](https://console.tailscale.com/admin/machines) once it joins. Task
nodes are preauthorized and skip device approval, so the tags and your policy file control what
they can reach. If a
task fails to join, the token exchange error shows on the credential in Trust credentials.

Some environment types don't support Tailscale. In those, tasks don't join the tailnet, and
`ns tailscale configure` reports that Tailscale isn't supported.

When network egress is restricted, Niteshift allows `*.tailscale.com` automatically, and tailnet
traffic goes through Tailscale's DERP relays. See [Tailscale's workload identity federation
guide](https://tailscale.com/docs/features/workload-identity-federation) and
[tags](https://tailscale.com/kb/1068/tags) for the Tailscale-side setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.