Get started - it's free!
Login
© 2025

Tailscale on Koyeb

Koyeb is a serverless platform for seamlessly deploying AI applications and databases on high-performance infrastructure, including CPUs, GPUs, and Accelerators around the world. You can add Tailscale to a Koyeb application to let your Koyeb Services communicate with other devices and services in your tailnet.

Step 1: Generate an auth key to authenticate your Service on Koyeb

Start by generating an auth key to let your Koyeb service join your tailnet.

Open the Keys page of the admin console and select Generate auth key. It's best practice to use a reusable and pre-authorized ephemeral key for this purpose because it automatically cleans up devices after they shut down.

Tailscale's auth key generation page

The Pre-approved option will only display in the dialog if device approval is enabled in your Tailscale network.

Next, open a terminal and use the following command to create a Koyeb Secret to securely store the auth key on Koyeb.

koyeb secrets create TAILSCALE_AUTHKEY -v "tskey-<key>"

Pass this Secret using an environment variable to your Koyeb Service to authenticate your application and join your tailnet.

Step 2: Configure your Dockerfile to install Tailscale

Next, build a multistage Dockerfile with two stages:

  • The first stage compiles and builds your application code.
  • The second stage pulls your application code and Tailscale into a final image that you can deploy to Koyeb.

In your Dockerfile:

FROM alpine:latest as builder
WORKDIR /app
COPY . ./
# This is where you build the application code as well.

# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM alpine:latest
RUN apk update && apk add ca-certificates iptables ip6tables && rm -rf /var/cache/apk/*

# Copy binary to production image.
COPY --from=builder /app/start.sh /app/start.sh

# Copy Tailscale binaries from the tailscale image on Docker Hub.
COPY --from=docker.io/tailscale/tailscale:stable /usr/local/bin/tailscaled /app/tailscaled
COPY --from=docker.io/tailscale/tailscale:stable /usr/local/bin/tailscale /app/tailscale
RUN mkdir -p /var/run/tailscale /var/cache/tailscale /var/lib/tailscale

# Run on container startup.
CMD ["/app/start.sh"]

The Dockerfile specifies the /app/start.sh script as the initial process to run. This script starts Tailscale, then runs the application binary. This is where you use the TAILSCALE_AUTHKEY variable you defined when you generated an auth key.

Create a new file named start.sh in the root directory of your application and add the following content to the file to start Tailscale and launch your app:

#!/bin/sh
# Start Tailscale
/app/tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/var/run/tailscale/tailscaled.sock &
/app/tailscale up --ssh --auth-key=${TAILSCALE_AUTHKEY} --hostname=tailscale-on-koyeb

# Start your app
/app/my-app

You pass the --ssh flag to /app/tailscale up to authorize SSH connections to the node. This will let you ensure everything is working as expected and let you connect to the node using SSH from your tailnet. To learn more about Tailscale SSH, refer to the Tailscale SSH documentation.

Save the file. You're ready to deploy.

Step 3: Deploy your app to Koyeb

To deploy the application on Koyeb, run the following command from your application's root directory. This command creates and deploys a new Koyeb service that connects to your tailnet:

koyeb deploy . myapp/main --instance-type small --region was --type worker --archive-builder docker --env TAILSCALE_AUTHKEY=@TAILSCALE_AUTHKEY --privileged

Run the following command to use SSH to confirm you can connect to the service:

tailscale ssh root@tailscale-on-koyeb

For more details about Koyeb, the Koyeb CLI, resources, service types, and deployment options, refer to the Koyeb documentation.

Remove ephemeral nodes from a tailnet

When an ephemeral node goes offline, it is automatically removed from your tailnet. You can also control ephemeral node removal using the tailscale logout command to either manually force the removal or incorporate the command into the tailscaled Tailscale daemon. For more information, refer to Ephemeral nodes.

Last updated Apr 23, 2025