Skip to main content
The Tailscale integration is currently in preview. Contact support if you’d like it enabled for your organization.

​
Overview

The Tailscale integration lets Tembo agent sessions join your 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:
  • Opt-in per task — sessions never join your tailnet automatically. An agent connects only when a task needs private-network access, using the managed /tailscale skill the integration installs.
  • 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, declare the tag in tagOwners:
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:
If you want agents to SSH into hosts via Tailscale SSH, add an ssh rule as well:
4

Create an OAuth client

In 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.

​
Advanced

  • 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.
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.
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.
  • 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.