atproto-tailnet

Managing Your Network

This guide describes the daily operations in the dashboard: devices, members, permissions, security, and networking.

Who gets a tailnet

The instance is invite-only:

When an operator designates you as a tailnet creator, you can create your tailnet in one of these ways:

Give a web application a secure address

A web application on one of your devices can get an address such as https://food-app.ts.example.com. The address works inside the tailnet only, and it has a valid certificate.

  1. Open the Boards tab and add a service: select the device, type the port, and give it a name.
  2. Select This is a web application: give it a secure web address.
  3. On your private board, the address works on your own devices. On the public board, it works for members after the approval and after they select Connect.

The application must listen on the tailnet address of the device (or on all addresses), not only on localhost.

The application receives two headers that tell it who is calling: X-Tailnet-User (the sign-in name) and X-Tailnet-Device (the name of the device). A visitor cannot set these headers.

A person who is not allowed to see the service gets the same answer as for a name that does not exist. From the public internet the address does not work.

If you do not see the option, the instance does not run the gateway.

Lock sign-in to your devices

You can limit sign-in to devices that you trust. Open the Account tab.

  1. Select Trust this device and turn the lock on. The browser makes a key that it keeps and does not show to anybody. The service stores only the public part.
  2. Save the recovery codes. The service shows them one time.
  3. From now on, a sign-in from another device is refused, also with the correct AT Protocol account. You get a notification.

To add a device: sign in on it and select Ask for approval. It shows a code. On a trusted device, open Account, type the code, and select Approve. You can set the maximum number of trusted devices.

If you lose all trusted devices, use a recovery code. Each code works one time. Then you must trust the device that you use. If you have no code, a person with access to the server can reset the lock with node dist/scripts/reset-device-lock.js <handle> in the app container.

The key and a device cookie are in the data of the browser. A sign-in needs the two. If you clear the data or the cookies of the browser, the device is not trusted any more. Approve it again from another trusted device, or use a recovery code.

If a trusted device signs in from a browser that looks different (another system, another browser), the sign-in works but the Account tab shows a warning on that device and you get a notification. If it was not you, remove the device. If it was you, select This was me.

Lock your tailnet devices

You can limit your devices in a tailnet to the machines that you have now. Open the Devices tab and find Lock my devices.

  1. Select Lock to my devices and select the devices that stay. The other devices of yours are removed from the tailnet.
  2. While the lock is on, no other machine can join as you. A valid auth key or the correct sign-in does not help.
  3. To add a device, select Allow one new device and connect the device in the next 10 minutes. Only one device gets in.

The card shows the machines that were refused. If you have trusted devices, each change of this lock needs a trusted device.

Appearance

Select a colour theme in the Account tab. The theme is saved in the browser.

What sign-in can access

Sign-in asks your AT Protocol server for one thing: proof of who you are (the atproto scope). The service cannot read or write your posts, follows, messages or settings. The service revokes the sign-in token as soon as it knows your account, and it keeps no token for your account. Your handle, display name and avatar come from public sources.

Your session in the dashboard is a cookie of this service. It stays valid for 7 days.

Dashboard overview

The dashboard is a React 19 single-page application. It is served at the root URL of your instance. Your permissions control which tabs you see.

Network

Manage

Access Control

Admin

Account

Operator (instance operators only)

The header has a notification bell. It shows approval requests and limit hits for the current tailnet.

Inviting members

An invitation is the allow-list entry for one person. The service does not send anything. You share the link.

  1. Go to the Invite tab.
  2. Enter a handle (for example, alice.bsky.social) or a DID (did:plc:... or did:web:...).
  3. Copy the invitation link (https://<APP_DOMAIN>/invite/<id>).
  4. Send the link to the invitee by any channel.
  5. The invitee opens the link and signs in. The invitee then accepts or declines.

After acceptance, the invitee becomes a member with the default role (“citizen”). Only the invitee can see the invitation. Other users get “not found”. Pending invitations also show in the no-access view of the invitee.

You can revoke an invitation before the invitee accepts it. Lockdown mode blocks new invitations and acceptances. If the tailnet has a member limit, acceptance fails when the tailnet is full.

Join requests

Join requests are an alternative to invitations. Turn on allowJoinRequests in the Security tab. Then:

The default tailnet of the instance accepts join requests automatically. People with no access see its Request to join button.

Join requests have these limits:

Roles and permissions

Every network has two built-in roles:

Custom roles

Create custom roles with any combination of 17 permissions:

Permission Description
invite Send invitations to new members
kick Remove members from the network
manage_roles Create, edit, and delete roles and assign them
manage_settings Change tenant settings (posture, hibernation, and others)
approve_devices Approve pending device connections
approve_joins Approve join requests
approve_services Approve service registrations
lock_devices Bind members to specific machine keys
view_audit_log Read the audit trail
manage_devices Manage nodes (rename, remove, routes)
manage_services Register and manage services
manage_board Moderate the public board
create_posts Post to the public board
create_agent_tokens Generate API tokens
manage_agent_tokens Revoke the API tokens of any member
manage_acl Edit ACL policy and DERP configuration
manage_sub_collectives Create and manage sub-collectives

Assign roles to members in the Members tab. The effective permissions of a member are the union of the permissions of the role of that member.

Boards and sharing

A tailnet has three boards.

Board Who sees it What it contains
Controller board Anybody on the internet Text from the originator about the tailnet
Public board Members of the tailnet Services that members offer
Private board You only Services that you run for your own devices

Device access

In a new tailnet, a device can reach only the other devices of its owner. Two things open more access: a service on the public board, and a share between friends. The originator, or a member with the manage_acl permission, can change the tailnet to open access (each device reaches each other device) in the Boards tab.

Offer a service

  1. Open the Boards tab and go to Add a service.
  2. Select the board, one of your devices, and one port. Give a title.
  3. A service on the private board is active at once. A service on the public board needs an approval from an operator of the tailnet (the originator, or a member with approve_services).

A service offers only its one port. Other ports of the device stay private.

Connect to a service

On the public board, select Connect next to a service and select one or more of your devices. Those devices can then reach that one port. You can disconnect at any time. If the author removes the service, or an operator withdraws the approval, all devices lose the access at once.

Friends and shares

Use the Friends & Sharing tab to share a device with one member.

  1. Send a friend request. The other member accepts it.
  2. Offer one of your devices, or ask for a device of your friend. Give the ports and how long the share lasts.
  3. The share is active only after the other member accepts it. Until then nothing is open.

Each of you can end a share at any time. If you remove a friend, all shares between you end. You can block a member; a blocked member cannot send you friend requests. Operators cannot see or change the shares of other members.

Controller board

The originator writes the public page of the tailnet in the Boards tab. The text can have headings, lists, bold, italic and https:// links. HTML and scripts are shown as text. The page is at /board/<tailnet-address>. The sign-in page shows the controller board of the default tailnet.

Device management

Connecting devices

Members generate pre-authentication keys in the Add Device tab. A key authorizes a Tailscale client to join the network:

tailscale up --login-server=https://control.yourdomain.com \
             --authkey=tskey-auth-XXXXX

The Add Device tab shows the exact command. In coordinator mode with CONTROL_DOMAIN set, all tailnets use one login server. The key selects the tailnet. Without CONTROL_DOMAIN, and in legacy Headscale mode, each tailnet has its own login server at https://<tailnet-address>.<BASE_DOMAIN>.

The device belongs to the member who made the key.

Sign in a device without a key

A device can also join without a key. Start the Tailscale app with the login server of the instance and select Sign in. The app opens a page of this service. Sign in with your AT Protocol account, check the name of the device and the key fingerprint, select the tailnet, and select Add device. The link is valid for 10 minutes and works one time.

In a tailnet that requires device approval, only the originator can add a device this way. Other members ask for a key in the Add Device tab.

Tailnet address

Each tailnet has a public address, for example quiet-harbor-4821.ts.yourdomain.com. Join links and board links use it. A new tailnet gets a random address. The address never contains your handle.

The originator can change the address in the Status tab (Tailnet address):

Auth keys

The service records each key that it issues. The Devices tab lists the keys:

Device approval

By default, devices connect without approval. When you turn on requireDeviceApproval (Security tab):

Device and member limits

The originator can set maxDevices and maxMembers in the Usage tab (0 = unlimited). There are no plans. The service enforces the limits:

When a limit stops an action, the service notifies the originator. A sub-collective cannot have higher limits than its parent.

Removing a member

When you remove (kick) a member, the service also revokes the auth keys of the member and deletes the devices of the member. You need the kick permission. Nobody can remove the originator.

Device locking

Device locks bind a membership to specific machine keys:

Node operations

In the Devices tab, members with the manage_devices permission can do these tasks:

Each member can remove their own devices.

Notifications

The service makes a notification for these events:

The recipients are the originator and the members with the matching approve_* permission. The bell in the header shows them.

Webhook

You can also send each notification to a webhook, for example a self-hosted ntfy, Gotify, or a Matrix bridge. In the Security tab, set the webhook URL and a secret (the manage_settings permission is necessary). Then:

Access control (ACL)

The ACL tab provides a policy editor. The policy controls which devices can talk to each other. The policy uses the Tailscale ACL format.

In coordinator mode (the default), the coordinator has no users, groups or tags. The service accepts only accept rules with *, IP addresses, CIDRs or host aliases. It refuses groups, tagOwners and autoApprovers:

{
  "hosts": {
    "server1": "100.64.0.1"
  },
  "acls": [
    {
      "action": "accept",
      "src": ["100.64.0.0/10"],
      "dst": ["server1:80,443"]
    }
  ]
}

In legacy Headscale mode, the full Headscale policy is available:

{
  "groups": {
    "group:admins": ["alice.bsky.social"]
  },
  "hosts": {
    "server1": "100.64.0.1"
  },
  "acls": [
    {
      "action": "accept",
      "src": ["group:admins"],
      "dst": ["*:*"]
    },
    {
      "action": "accept",
      "src": ["*"],
      "dst": ["server1:80,443"]
    }
  ],
  "tagOwners": {
    "tag:server": ["group:admins"]
  }
}

Changes take effect immediately when you save them.

Networking

Exit nodes

An exit node routes all internet traffic of a device through another device on the network. Devices advertise the exit node capability. A member with manage_devices approves or withdraws the capability in the Routes tab.

Subnet routers

Subnet routers advertise access to physical network subnets (for example, 192.168.1.0/24). Network members can then reach devices on a LAN. You do not install Tailscale on each device. As with exit nodes, a member with manage_devices must approve subnet routes. Until then, the route has no effect.

IP ranges

Each network receives a default IP range in the CGNAT space (100.64.0.0/10 for IPv4, fd7a:115c:a1e0::/48 for IPv6). You can change these ranges in the IP Ranges tab. You can choose these settings:

When you change IP ranges, you must restart the control plane. You must also register all devices again.

DERP relays

DERP relays provide encrypted relay connectivity when direct peer-to-peer connections fail (for example, behind restrictive NATs). In coordinator mode, the default is the built-in relay of the instance (see the coordinator guide). No traffic goes through Tailscale relays. In the DERP Relays tab you can do these tasks:

The settings apply to your tailnet only. In coordinator mode, connected devices get the new relay map at once.

Agent tokens

Agent tokens give programmatic API access to automation, CI/CD, and AI agents:

Create tokens in the Agents tab. The dashboard shows the token value once, when you create the token.

Using agent tokens

curl https://yourdomain.com/api/tenants/<id>/devices \
  -H "Authorization: Bearer at_XXXXX"

An agent token can access each endpoint that its permission scope allows. The token is restricted to its tenant. It never gives instance operator powers.

To use the API from Claude, use the MCP server, not an agent token. See Connect Claude (MCP).

Security settings

The Security tab controls the security toggles for the whole tenant:

Setting Default Description
requireDeviceApproval off Gate new device connections behind approval
requireServiceDeviceApproval off Gate service device registrations
requireServiceApproval off Gate service registrations
allowJoinRequests off Enable public join request page (on for the default tailnet)
allowAgentTokens off Enable API token creation
allowMemberAgentTokens off Allow non-originators to create tokens
boardEnabled off Enable the public service board
notificationWebhookUrl — Webhook for notifications. See Webhook

Lockdown mode

Lockdown is an emergency switch. It immediately blocks these actions:

Lockdown does not disconnect existing devices. It does not revoke existing tokens. It prevents the grant of any new access.

Audit log

The system logs each security-relevant action to the audit trail. You can view the trail in the Audit tab (the view_audit_log permission is necessary). The system logs these actions:

Each audit entry includes the user ID of the actor, the timestamp, the action type, and relevant metadata.

Usage and limits

The Usage tab shows these items:

The system stores usage snapshots in the usage_snapshots table. The dashboard shows them as a sparkline chart.

Instance hibernation

To save resources, the system can stop idle networks automatically:

Instance administration

The Instance tab is visible only to instance operators. It has these functions:

Suspend a tailnet

Suspension stops a tailnet without deleting it:

Disable a user

A disabled user cannot sign in. Each credential of the user stops working, including agent tokens and MCP connections. The service also does these steps:

Enable lets the user sign in again. The removed memberships do not come back.

Default tailnet and single-tailnet mode

The first tailnet that an operator creates becomes the default tailnet. It accepts join requests. When you select a different default tailnet, the service turns on join requests for it. Select None to have no default tailnet. People with no access then see only their invitations.

In single-tailnet mode, the instance has only one top-level tailnet. Nobody can create a second one, and nobody can create sub-collectives. You cannot turn on this mode when more than one top-level tailnet exists.