Docker Login for Larktun: Userspace and TUN Modes

Larktun provides a multi-architecture Docker image that connects Linux servers, NAS devices, gateway hosts, and other containerized systems to a Larktun network. This guide covers both login methods:

• Userspace mode: requires fewer privileges and does not need a TUN device on the host.
• Kernel TUN mode: uses the host network stack and is designed for Linux systems that need full networking or subnet-routing capabilities.

Whichever mode you choose, use an Auth Key created in the Larktun console and set the login server to https://hs.larktun.com.

The Auth Key must come from Larktun

Do not use a key from the Tailscale admin console. The Auth Key in this guide must be created in the Larktun console. Treat it like a device password: never commit it to Git or include it in chats, tickets, or screenshots.

Before you begin

• A Linux server, NAS, or other device with Docker installed and running.
• A working Larktun account.
• An available device slot on your account.
• Network access to the image registry at registry.larktun.com and the login server at https://hs.larktun.com.

First, confirm that Docker is running:

docker version

1. Pull the Larktun Docker image

The currently recommended image is:

docker pull registry.larktun.com/larktun/larktun:latest

The latest tag is a multi-architecture image. Docker automatically selects the image for your host:

• linux/amd64: common x86-64 servers, PCs, and virtual machines
• linux/arm64: ARM64 NAS devices, ARM servers, and Apple Silicon Linux virtual machines
• linux/arm/v7: selected 32-bit ARM devices

Production recommendation

After testing, replace latest with a validated version tag or image digest to make rollback and troubleshooting easier.

2. Create an Auth Key in the Larktun console

1. Sign in to the Larktun console and enter your tenant or workspace.
2. Open Nodes (Devices) from the left navigation.
3. Click Create Auth Key to create a dedicated key for this Docker device.
4. Copy and store the key immediately. It is usually shown in full only once.

Do not share one Auth Key across desktop clients, routers, and other servers.

To keep the key out of your shell history, run the following in Linux Bash:

read -rsp "Paste your Larktun Auth Key (input is hidden): " TS_AUTHKEY && echo
export TS_AUTHKEY

The Docker commands below read this temporary environment variable. Do not paste a real key into this document or commit it to a repository.

3. Choose a login mode

Both modes log the Docker node in to Larktun, but their networking capabilities and privilege requirements differ. Choose only one; do not start two containers with the same name.

Comparison	Userspace mode	Kernel TUN mode
Requires /dev/net/tun	No	Yes
Extra privileges	No NET_ADMIN required	Requires NET_ADMIN and NET_RAW
Uses host networking	No	Yes, with --network=host
Best for	Low-privilege login, container access, SOCKS5/HTTP proxy	Full Linux host networking and subnet routing
Suitable for advertising host subnets	No	Yes

If you are unsure, start with userspace mode. Choose Kernel TUN only when you specifically need host routes or subnet routing.

4. Option 1: Log in with userspace mode

Userspace mode is the default. It does not require --network=host, NET_ADMIN, or /dev/net/tun. Run:

docker run -d --name larktun \
  --restart unless-stopped \
  -e TS_AUTHKEY \
  -e TS_EXTRA_ARGS="--login-server=https://hs.larktun.com" \
  -e TS_USERSPACE="true" \
  -e TS_STATE_DIR="/var/lib/larktun" \
  -e TS_HOSTNAME="larktun-userspace" \
  -e TS_AUTH_ONCE="true" \
  -v larktun-state:/var/lib/larktun \
  registry.larktun.com/larktun/larktun:latest

This mode joins the container to Larktun, but it does not automatically add Larktun routes to the host and cannot advertise the host subnet.

If a host application needs to reach the Larktun network through a proxy, add these options when creating the container to enable SOCKS5 and HTTP proxies bound to localhost only:

-p 127.0.0.1:1080:1080
-p 127.0.0.1:8080:8080
-e TS_SOCKS5_SERVER=0.0.0.0:1080
-e TS_OUTBOUND_HTTP_PROXY_LISTEN=0.0.0.0:8080

The proxy URLs are socks5://127.0.0.1:1080 and http://127.0.0.1:8080. Do not bind these proxy ports to a public interface without access controls.

5. Option 2: Log in with Kernel TUN mode

Kernel TUN mode uses the host network namespace and creates Larktun-related interfaces and routes. It is intended for Linux servers that need full networking and is required when advertising subnet routes from Docker.

First, confirm that the host has a TUN device:

ls -l /dev/net/tun

Then run:

docker run -d --name larktun \
  --restart unless-stopped \
  --network=host \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --device=/dev/net/tun:/dev/net/tun \
  -e TS_AUTHKEY \
  -e TS_EXTRA_ARGS="--login-server=https://hs.larktun.com" \
  -e TS_USERSPACE="false" \
  -e TS_STATE_DIR="/var/lib/larktun" \
  -e TS_HOSTNAME="larktun-tun" \
  -e TS_AUTH_ONCE="true" \
  -e TS_PRESERVE_UNDERLAY_ROUTES="true" \
  -v larktun-state:/var/lib/larktun \
  registry.larktun.com/larktun/larktun:latest

TS_PRESERVE_UNDERLAY_ROUTES=true protects the host's existing underlay network and DNS routes. If a cloud provider uses DNS addresses inside 100.64.0.0/10, you can also set TS_PRESERVE_UNDERLAY_DNS to the actual addresses. Common Alibaba Cloud addresses, for example, are 100.100.2.136,100.100.2.138.

To reach a LAN behind the host, set TS_ROUTES in TUN mode and approve the advertised routes in the console. See Approve subnet routes for the complete procedure.

Deploy a TUN subnet router with Docker Compose

To keep the deployment configuration in one reusable file, create compose.yaml in your deployment directory. This example uses Kernel TUN mode and advertises the host LAN subnet 192.168.1.0/24:

compose.yaml

services:
  larktun:
    image: registry.larktun.com/larktun/larktun:latest
    container_name: larktun
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      TS_AUTHKEY: "replace-with-your-auth-key"
      TS_EXTRA_ARGS: "--login-server=https://hs.larktun.com"
      TS_USERSPACE: "false"
      TS_STATE_DIR: "/var/lib/larktun"
      TS_HOSTNAME: "larktun-subnet-router"
      TS_ROUTES: "192.168.1.0/24"
      TS_PRESERVE_UNDERLAY_ROUTES: "true"
      TS_PRESERVE_UNDERLAY_DNS: "100.100.2.136,100.100.2.138"
    volumes:
      - larktun-state:/var/lib/larktun

volumes:
  larktun-state:

Before deployment, change:

• Replace replace-with-your-auth-key with an Auth Key created in the Larktun console.
• Replace 192.168.1.0/24 with the actual LAN subnet the host should advertise. Separate multiple subnets with commas.
• 100.100.2.136,100.100.2.138 are common Alibaba Cloud underlay DNS addresses. Use the actual DNS addresses in other environments, or remove TS_PRESERVE_UNDERLAY_DNS when manual protection is unnecessary.

Protect the Auth Key in compose.yaml

This example stores the Auth Key in compose.yaml. Restrict access to the file, add it to .gitignore, and never commit the real key. Use protected secret management for stricter production environments.

Start the deployment and check its status:

docker compose up -d
docker compose ps
docker compose logs --tail=80 larktun
docker compose exec larktun larktun status

After the device comes online, approve the subnet advertised by TS_ROUTES in the Larktun console. Other devices will not use the subnet route until it is approved.

When updating the image and recreating the container later, the larktun-state volume preserves the node state:

docker compose pull
docker compose up -d

6. Confirm a successful login

If you used the earlier docker run method and temporary environment variable, first clear the key from the current terminal:

unset TS_AUTHKEY

Then check the container, its logs, and the Larktun status:

docker ps --filter name=larktun
docker logs --tail=80 larktun
docker exec -it larktun larktun status

A successful login has all three signals:

1. The larktun container is running in docker ps.
2. larktun status lists devices in the current Larktun network.
3. After you refresh Nodes (Devices) in the Larktun console, the new Docker node appears online.

Node state is stored in the larktun-state volume. Mount the same volume when recreating the container and keep TS_AUTH_ONCE=true so an existing node does not use the Auth Key again unnecessarily.

Troubleshooting

The Docker device does not appear in the console

Make sure the Auth Key came from the Larktun console and has not expired or been revoked. Check that TS_EXTRA_ARGS contains the complete value --login-server=https://hs.larktun.com, then inspect docker logs --tail=80 larktun for the exact error.

A duplicate device appears after a container restart

Confirm that the command includes TS_STATE_DIR=/var/lib/larktun, TS_AUTH_ONCE=true, and -v larktun-state:/var/lib/larktun. Removing a container does not automatically remove its volume, but using a new volume loses the existing node state.

TUN mode reports that /dev/net/tun is missing

The host kernel may not have TUN/TAP loaded, or the Docker environment may not allow the device mapping. Fix TUN support on the host first. If the environment cannot provide TUN, use userspace mode.

DNS resolution fails after TUN mode starts

Keep TS_PRESERVE_UNDERLAY_ROUTES=true. If the cloud provider's underlay DNS addresses are inside 100.64.0.0/10, set the actual addresses with TS_PRESERVE_UNDERLAY_DNS, then recreate the container. For complete Alibaba Cloud ECS diagnostics, see Larktun on Alibaba Cloud: Fix Linux and Docker DNS Failures.

A container named larktun already exists

When switching modes, remove the old container before running the command for the selected mode:

docker rm -f larktun

This command does not delete the larktun-state volume. Do not delete that volume unless you intend to log out and erase the saved node state.

Updates and routine operations

# Show the installed version
docker exec -it larktun larktun version

# Follow logs
docker logs -f larktun

# Pull the recommended image
docker pull registry.larktun.com/larktun/larktun:latest

# Restart without deleting saved state
docker restart larktun

Next steps

• Approve subnet routes
• Publish your first secure service
• Log in with the Tailscale client
• Troubleshooting