Set up Tailscale for boxes.dev

Before you start

You need:

• Tailscale Owner or Admin access. If your organization splits network-policy and device administration between roles, those administrators may need to complete their respective steps.
• The Tailscale users or groups that should be allowed to enable Tailscale for boxes.dev projects.
• The tailnet resources and ports that project machines should be able to reach.

If Tailnet Lock is enabled, stop here and contact boxes.dev. Tailnet Lock is not supported by this integration yet.

1. Create a dedicated project-machine tag

Open Tags in the Tailscale admin console, then select Create tag.

• Tag name: boxes-dev (Tailscale will display it as tag:boxes-dev)
• Tag owners: leave empty unless your organization requires an explicit administrative owner
• Note: boxes.dev project machines (optional)

Save the tag. Do not assign it to an existing device. The tag must have no devices when boxes.dev connects and must remain dedicated to boxes.dev. Do not configure tag:boxes-dev as the owner of another Tailscale tag; devices enrolled through a child tag would be outside boxes.dev's device inventory and cleanup.

Record this value:

• Project machine tag: tag:boxes-dev

2. Grant access in Tailscale policy

Open General access rules.

First, give the intended boxes.dev project owners unconditional access to the new tag. Select Add rule and use:

• Source: the Tailscale user or group allowed to enable Tailscale for a boxes.dev project, such as group:engineering
• Destination: tag:boxes-dev
• Port and protocol: All ports and protocols
• Device posture: none

If an existing rule already provides this unconditional user-or-group to tag path, do not add a duplicate. boxes.dev will verify that a project owner's verified boxes.dev email exactly matches an active, approved Tailscale user and that this policy path exists. Access that depends only on the posture of a personal device will not qualify because a project machine is a separate tagged device.

Second, decide what project machines may initiate connections to. Add a separate least-privilege rule with:

• Source: tag:boxes-dev
• Destination: only the company resource tags, services, IP sets, hosts, or subnets the project machines need
• Port and protocol: only the required ports and protocols

For example, the underlying grants could look like this after replacing the example group and resource tag with your own:

{
  "grants": [
    {
      "src": ["group:engineering"],
      "dst": ["tag:boxes-dev"],
      "ip": ["*"]
    },
    {
      "src": ["tag:boxes-dev"],
      "dst": ["tag:internal-development"],
      "ip": ["tcp:443", "tcp:5432"]
    }
  ]
}

The first rule controls who may verify and enable the integration. The second controls what connected Template boxes and devboxes may reach. Anyone who can run commands or automations on an enabled project machine can use that machine's network access, so keep the second rule narrow.

3. Create a tag-scoped OAuth credential

Open Trust credentials, select Credential, then select OAuth. In Settings, give the credential a recognizable name such as boxes.dev. Continue to Scopes and choose Custom scopes.

Select exactly these permissions:

Tailscale will also show Read selected when a Write scope includes it. Leave every other scope unchecked. In both tag selectors, choose only tag:boxes-dev.

Select Save changes. On the credential-created screen, immediately copy:

• OAuth client ID
• OAuth client secret

The secret is case-sensitive and is displayed only once. Store it in your organization's approved secret manager or one-time sharing tool.

These permissions let boxes.dev create short-lived enrollment keys and manage devices carrying only tag:boxes-dev. The read scopes let boxes.dev evaluate project-owner eligibility and read the tailnet's device and user directories, policy, and device posture attributes. boxes.dev will not edit the tailnet policy.

4. Copy the Tailnet ID

Open Tailscale General settings. Under Unique IDs, copy the value labeled Tailnet ID.

A current Tailnet ID looks like T123456789CNTRL. Copy the exact value shown in Tailscale.

Values to return

Return these four values to the boxes.dev requester:

The Tailnet ID, tag, and client ID are identifiers. Treat the OAuth client secret as a secret and send it only through your organization's approved secure channel. Do not put it in ordinary email, a ticket, or a persistent chat message.

The boxes.dev team admin will enter all four values and select Connect Tailscale. boxes.dev will validate the Tailnet ID, required scopes, tag authority, and that the tag has no devices before storing the encrypted secret.

Troubleshooting

• The tag is not available in the OAuth form: confirm that tag:boxes-dev was saved under Access controls -> Definitions -> Tags.
• boxes.dev says the tag is not empty: remove existing devices from this tag or create a new dedicated tag, then create a credential scoped to that tag.
• boxes.dev reports a missing scope: compare the OAuth credential with the five rows in step 3. Both Devices -> Core and Keys -> Auth Keys need Write and the exact tag.
• A project owner cannot verify access: confirm that their verified boxes.dev email exactly matches an active, approved email-based Tailscale login and that an unconditional user-or-group to tag:boxes-dev rule exists. GitHub-only and passkey-only Tailscale login names are not supported yet.
• The OAuth client secret was shared insecurely: revoke that credential in Tailscale, repeat step 3 to create a replacement, and send the new secret through an approved secure channel. If boxes.dev was already connected, rotate the credential there too.
• Tailnet Lock is enabled: contact boxes.dev for help before trying to connect the integration.