---
title: "Join a paid sandbox to your Tailscale network with your auth key."
method: POST
path: "/v1/sandboxes/{id}/tailscale"
tags: ["tailscale"]
---

# Join a paid sandbox to your Tailscale network with your auth key.

`POST /v1/sandboxes/{id}/tailscale`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}/tailscale`
- Auth: HTTP bearer

The auth key is read from your job secret and given to the sandbox's tailscaled in memory; it is never answered, logged or written to the sandbox's disk. The machine is ephemeral: logging out takes it off the tailnet at once, and after a stop or a delete Tailscale removes it once it has been offline a while. The first join in a sandbox downloads Tailscale, which takes a few seconds more. While it is on a tailnet a sandbox is not forked or snapshotted from memory.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `authKeySecret` string, required: The name of a job secret holding a Tailscale auth key (runtime secrets set NAME --jobs). Use an ephemeral, tagged key; a reusable one lets the sandbox log in again by itself after a long pause.
  - `hostname` string: The machine's name on the tailnet, a DNS label. Default: the sandbox's name, or runtime- and its id's first eight characters.
  - `tags` string[]: Tailscale tags to advertise; the key must be allowed them.

## Response `200`

Success

- object
  - `running` boolean, required
  - `state` string, nullable
  - `mode` string, nullable
  - `hostname` string, nullable
  - `dnsName` string, nullable
  - `addresses` string[], required
  - `proxy` string, nullable

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)