tailscale-macos-container

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #go #android #rust #deep-learning #docker #windows #awesome-list #security #ios #openai

tailscale-macos-container

(★ 20)

Using Tailscale with Apple's containerization stack on macOS

tailscale-macos-container Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Using Tailscale with Apple's containerization stack on macOS

This repository demonstrates how to use Apple's macOS containerization stack to provision an Alpine Linux instance, and then add it to your tailnet.

Apple's macOS containerization stack uses the Virtualization framework to spin
up a minimal Linux host VM for each container instance. Since neither the macOS
host kernel nor the specialized Linux guest VM kernel includes a native
WireGuard kernel module, the container must run Tailscale in userspace
networking mode instead of attaching to a standard kernel TUN device.

The container example in this repo starts `tailscaled` with
`--tun=userspace-networking`, authenticates the node using a Tailscale auth key
and then enables Tailscale SSH. Once the container joins your tailnet, you can
use Tailscale MagicDNS for naming and then connect to the container over
Tailscale SSH without exposing any ports on the host or configuring a separate
SSH server inside the container.

This example also demonstrates a macOS-specific method of securely storing your Tailscale auth key in Apple Keychain.

## Modify access controls

### Create a tag

[Access controls > Tags](https://login.tailscale.com/admin/acls/visual/tags)

* **Tag name:** `myservers`
* **Tag owners:** `your-email@example.com`

### Modify the Tailscale SSH access controls

Go to [**Access controls > Tailscale SSH**](https://login.tailscale.com/admin/acls/visual/tailscale-ssh/) and ensure your policy permits access to the tagged servers and specified users:

```json
{
  "action": "accept",
  "src": ["autogroup:admin"],
  "dst": ["tag:myservers"],
  "users": ["player1", "player2"]
}
```

* Add your new tag (`"myservers"`) to the **Destination** (`dst`) array.
* Add the Linux usernames defined in your `cloud-config` (`"player1", "player2"`) to the **Destination users** (`users`) array.
* Change `"action"` from `"check"` to `"accept"` for seamless SSH access.

## Create a Tailscale auth key

1. Generate an auth key via the [Tailscale Admin Keys panel](https://login.tailscale.com/admin/settings/keys) with these configurations:
* **Reusable:** Enabled
* **Pre-authorized:** Enabled
* **Tags:** Choose the newly created tag: `tag:myservers`

2. Store the newly created auth key in Keychain:

```
./store-ts-key-keychain.sh
```

*(Note: This creates an entry named `tailscale-auth-key-alpine-ts-server` in your Keychain).*

## Build the image

```
./build.sh
```

## Run the container

```
./run.sh
```

## Connect to the container

Once `run.sh` finishes authenticating the machine, you can connect directly over your tailnet using Tailscale SSH or jump straight into the machine locally via OrbStack:

* **MagicDNS name:** `ssh player1@alpine-ts-server`
* **built-in local SSH proxy:** `ssh player1@alpine-ts-server@orb`
* **CLI:** `orb -m alpine-ts-server`

## Files

`Containerfile` and `tini-start.sh` should work on other OCI‑compatible
container platforms. However, those platforms typically provide a kernel TUN
device, so this userspace networking technique is mainly a macOS‑specific
workaround rather than a general best practice.

Additional helper scripts provide macOS‑specific integration with Apple's
`container` CLI:

- `build.sh`: Builds the container image.
- `run.sh`: Launches a container instance and retrieves the Tailscale auth key
  from Apple Keychain. It also demonstrates how to mount a local folder into
  a container using the `--volume` command-line option.
- `cleanup.sh`: Removes the container from your tailnet, removes the container
  instance and deletes the container image.
- `store-ts-key-keychain.sh`: Copies the Tailscale auth key from the system
  clipboard to Apple Keychain for later use by `run.sh`.

tailscale-macos-container

tailscale-macos-container Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

tailscale-macos-container

tailscale-macos-container Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README