Connect Tailscale

Use Tailscale to let your cloud devboxes reach private company services, such as an internal database. Your Tailscale administrator controls which services the machines can reach. After team setup, enable the integration for your project without signing in to Tailscale on each machine.

Arrange team setup

If your team hasn't connected Tailscale yet, send the public Tailscale administrator guide to whoever manages your company's tailnet, the private network in Tailscale. They can read the guide without a boxes.dev account.

The Tailscale administrator needs to prepare a dedicated tag:boxes-dev, access rules, and a tag-scoped OAuth client, then send four values through your company's secure channel: the Tailnet ID, tag, client ID, and client secret.

If you're a boxes.dev team admin, enter those values in the project's Integrations → Tailscale page or in Team Settings, then choose Connect Tailscale.

Team setup starts with the device tag and access rules for boxes.dev machines. Select the image to enlarge it.

Enable a project

Your verified boxes.dev email must match an active, approved email-based Tailscale login. Ask your Tailscale administrator to give your user or group unconditional access to the managed tag; the administrator guide shows them how.

That access rule determines who can enable the integration. Separate rules for the tag determine which private services connected machines can reach.

As the project owner:

1. In the desktop app, select your project and open Integrations → Tailscale.
2. Choose Verify Tailscale access.
3. After your access is verified, choose Enable Tailscale.

If verification fails, ask your Tailscale administrator to check the email and access rule. GitHub-only and passkey-only logins, and access rules that depend only on device posture, cannot satisfy this check.

Enabling authorizes the project's machines to enroll; it doesn't connect the machines you already have. Connect each current machine, including your Template box if the project has one, with tailscale up as described below. If you also want each future devbox to connect while it starts, turn on Connect new devboxes automatically; that setting doesn't change existing machines.

Once enabled, anyone or any automation that can run commands on the project's machines will be able to use their granted network access.

Connect and disconnect machines

You can connect an ordinary project's Template box and devboxes, or the assigned devboxes in a Member project. The private machine used to edit a Team Template stays outside the integration.

Open a terminal on the machine you want to connect and run:

tailscale up
tailscale status

boxes.dev will enroll the machine automatically. Once connected, commands and agents on that machine can reach the private services your Tailscale administrator has allowed for the managed tag. You can use the official Tailscale client's commands, including tailscale ping, to check connectivity.

To disconnect that machine while keeping its identity, run:

tailscale down

Run tailscale up to reconnect. If you instead run tailscale logout, the machine's local identity and ephemeral Tailscale device will be removed. A later tailscale up will request a fresh identity automatically; ignore the ordinary Tailscale login URL that can appear briefly, because boxes.dev completes the enrollment itself. If the machine doesn't reconnect, open Integrations → Tailscale to check your access, or contact boxes.dev support.

Connect new devboxes automatically is off by default and affects only devboxes created while it is on. Changing it will not connect or disconnect existing machines, and it will not override a later tailscale down or tailscale logout.

Expect identity changes

When you connect from another tailnet machine to a service running on a project machine, use its MagicDNS hostname; the machine's numeric Tailscale IP can change after a long sleep or a snapshot.

Short sleeps normally preserve the machine's identity. Tailscale can remove inactive ephemeral devices, and boxes.dev may remove a recorded device after its machine has been paused for at least 90 minutes. When the machine next connects, it may receive a new device entry and address in Tailscale.

Taking a snapshot to create a devbox will briefly disconnect the source machine from Tailscale and give it a fresh identity afterward. Its MagicDNS hostname will stay the same. Other devboxes will remain connected, and the new devbox will receive its own identity.

Remove access deliberately

To stop Tailscale access for one project, open its Tailscale integration page and choose Disable Tailscale, then confirm with Disable. boxes.dev will stop enrollment and remove that project's recorded devices.

Deleting a device only in Tailscale will disconnect its current identity, but an eligible project machine can later connect again with a new identity. For an immediate network cutoff, restrict the managed tag's network grants. To prevent a project from reconnecting, disable its integration or remove its owner's eligibility. To stop all projects, disconnect the team integration or revoke its OAuth client.

Tailnet Lock is currently unsupported. If it's enabled, contact boxes.dev support for help completing setup.

Team credentials and permissions

These rules are the Tailscale administrator's to set up; the administrator guide walks through them. The managed tag must be empty when connected, remain dedicated to boxes.dev, and not own another tag. The OAuth client permits boxes.dev to read the tailnet's policy, users, devices, and posture data. Device changes and auth-key creation are limited to the configured tag. The renewable OAuth secret stays encrypted in boxes.dev and is never sent to project machines.