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

# Tailscale

> Connect Tembo sandbox sessions to your private network (tailnet) with on-demand, single-use ephemeral keys.

![Tembo and Tailscale logos](https://mintcdn.com/test-8862363a/ELdizPTMKoP0wlbL/images/integrations/tailscale.png?fit=max\&auto=format\&n=ELdizPTMKoP0wlbL\&q=85\&s=606c3f04579435922e2a8a922c1a9708)

## Overview

The Tailscale integration lets Tembo agent sessions join your
[tailnet](https://tailscale.com/kb/1136/tailnet) so they can reach private
resources — internal databases, staging hosts, admin APIs — that aren't
exposed to the public internet.

It is designed to be safe by default:

* **Joins only when needed** — sessions don't join your tailnet by default.
  A session connects when an agent needs private-network access for a task,
  using the managed `/tailscale` skill the integration installs, or when it
  connects to an [MCP server you've set to reach via Tailscale](#private-mcp-servers).
* **Single-use, ephemeral keys** — each join uses a short-lived, single-use
  auth key minted on demand. Your Tailscale OAuth credentials never enter a
  sandbox, and ephemeral nodes remove themselves from your tailnet when the
  session ends.
* **Your ACLs decide access** — a joined session is just a tagged device on
  your tailnet. What it can reach is governed entirely by your Tailscale ACL
  policy for the tag you assign. No inbound access to the session is required
  or expected.
* **Unprivileged** — inside the sandbox, Tailscale runs in userspace
  networking mode with no root access and no kernel networking changes.

## Prerequisites

You need admin access to your Tailscale organization to complete the setup:

**1. Choose a device tag**

Sessions join your tailnet as tagged devices. We recommend a dedicated
tag such as `tag:tembo-session` so you can scope access rules to Tembo
sessions only.

**2. Add the tag to your tailnet policy**

In the [Tailscale admin console](https://login.tailscale.com/admin/acls),
declare the tag in `tagOwners`:

```jsonc theme={null}
"tagOwners": {
  "tag:tembo-session": [],
},
```

**3. Grant the tag access in your ACLs**

Add ACL rules for what Tembo sessions may reach. This is entirely your
choice — start narrow. For example, to allow sessions to reach a staging
database subnet and hosts tagged `tag:staging`:

```jsonc theme={null}
"acls": [
  {
    "action": "accept",
    "src":    ["tag:tembo-session"],
    "dst":    ["tag:staging:*", "10.20.0.0/16:5432"],
  },
],
```

If you want agents to SSH into hosts via
[Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh), add an
`ssh` rule as well:

```jsonc theme={null}
"ssh": [
  {
    "action": "accept",
    "src":    ["tag:tembo-session"],
    "dst":    ["tag:staging"],
    "users":  ["ubuntu"],
  },
],
```

**4. Create an OAuth client**

In [**Settings → Trust credentials**](https://console.tailscale.com/admin/settings/trust-credentials),
click **+ Credential**, select **OAuth**, and continue. Under **Keys →
Auth keys**, select the **Write** scope — read access is not enough,
because Tembo has to create keys. Then assign the client the tag you
created (`tag:tembo-session`). Tembo uses this client to mint short-lived
auth keys — it can only create keys for the tags it owns.

Copy the **client ID** and **client secret**; you'll enter them in Tembo
next.

## Installation

**1. Open Integrations**

In the Tembo app, go to **Settings → Integrations**.

**2. Install Tailscale**

Find **Tailscale** in the **Developer Tools** group and click
**Install**.

**3. Enter your OAuth client credentials**

Fill in a connection name, the OAuth **client ID** and **client secret**,
and the device tag(s) sessions should advertise (for example
`tag:tembo-session`).

Tembo validates the credentials against the Tailscale API before saving
— if the client ID or secret is wrong, you'll see an error immediately.

Installing the integration also creates a managed **`/tailscale`** skill for
your organization. This skill teaches agents how to join the tailnet and how
to reach hosts through it; you don't need to configure anything else.

## Usage

Ask an agent to do something that requires your private network, and mention
the tailnet or Tailscale if you want to be explicit:

* "Use tailscale to query the staging database and summarize yesterday's failed jobs."
* "SSH into the metrics host on our tailnet and check disk usage."
* "Hit the internal admin API and pull the feature-flag config."

The agent invokes the `/tailscale` skill, requests a one-time key from the
Tembo API, joins your tailnet as `tembo-session-<session-id>`, and does the
work. Sessions appear in your Tailscale admin console as tagged devices
while active and remove themselves when the session ends.

### Private MCP servers

Sessions can also use MCP servers that are only reachable on your tailnet.
Add the server as a custom remote MCP server with **Reach via Tailscale**
turned on, and allow your session tag to reach its port in your ACLs. See
[Private servers on your tailnet](https://docs.tembo.io/integrations/mcp.md#private-servers-on-your-tailnet).

## Advanced

> [accordion] Security model
>
> * Your OAuth client credentials are stored encrypted with the integration
>   and used only server-side by the Tembo API. They are never sent to a
>   sandbox.
> * When a session joins, the Tembo API mints a **single-use, ephemeral,
>   pre-authorized** auth key restricted to your configured tags, with an
>   expiry of minutes. That key is the only credential the sandbox ever
>   sees.
> * Sessions are outbound-only participants on your tailnet. Nothing on
>   your tailnet needs to (or should) connect into a session.
> * Removing the integration deletes the managed skill; you can also revoke
>   the OAuth client in Tailscale at any time to cut off all key minting.

> [accordion] How sessions connect
>
> Sandboxes run `tailscaled` in userspace networking mode (no root, no TUN
> device). Traffic to your tailnet flows through Tailscale's encrypted
> WireGuard tunnel, typically relayed over HTTPS (DERP) since sandboxes
> don't accept inbound UDP. Agents reach your hosts via Tailscale SSH, a
> local SOCKS5/HTTP proxy, or TCP tunneling — the managed skill covers all
> of this so agents handle it automatically.

> [accordion] Multiple tags or tailnets
>
> You can list multiple tags when installing (all must be owned by the
> OAuth client). The integration connects to the OAuth client's tailnet;
> to serve multiple tailnets, install the integration once per tailnet.

> [accordion] Troubleshooting
>
> * **Install fails with "Invalid Tailscale credentials"** — the client ID
>   or secret is wrong, or the OAuth client lacks the **Keys → Auth keys**
>   **Write** scope.
> * **Agent reports `requested tags are invalid or not permitted`** — the
>   tag you configured in Tembo isn't assigned to the OAuth client in
>   Tailscale (check both `tagOwners` and the client's tag assignment).
> * **Agent reports connections to a host time out** — your ACL policy
>   doesn't allow `tag:tembo-session` to reach that host and port. This is
>   Tailscale working as intended; extend your ACLs if the access is
>   wanted.
> * **A skill named `tailscale` already exists** — the integration installs
>   a managed `/tailscale` skill and won't overwrite a skill you authored
>   with the same name. Rename or delete yours and install again.


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