Tailscale for DDEV: Simple and Secure Project Sharing

I’ve found that DDEV’s ddev share command is a great way to quickly share my local development environment. However, since it uses ngrok, it requires ngrok to be installed on the host system and generates a new, random URL every time unless you use a stable domain. As an alternative, I’ve created the ddev-tailscale-router add-on.

This add-on uses Tailscale, a VPN service that creates a private and secure network between your devices. It is free for personal use and doesn’t require any additional software to be installed on your host system!

As a result, you get a stable, human-readable URL for each of your DDEV projects, which you can access from any device on your Tailscale network.

I’ve found this approach to be particularly useful for:

Cross-device testing: I can easily test my sites on my phone or tablet without being on the same Wi-Fi network.
Stable webhook URLs: I can use the permanent Tailscale URL as a reliable endpoint for webhooks, such as those from payment gateways.
Team collaboration: I can share my development environment with team members so they can see my work in progress.

How it Works

The ddev-tailscale-router add-on works by installing Tailscale directly into your DDEV project’s web container using userspace networking. This approach provides better macOS compatibility and improved reliability compared to running a separate container. The add-on automatically connects to your Tailscale network and securely proxies requests to your project.

Update (November 2026): A few things have changed since this post was published. The add-on now needs DDEV v1.25.4 or later, ddev tailscale login works without an auth key, a startup problem on DDEV v1.25 is fixed, and ddev tailscale share prints a QR code for the URL. If you’re upgrading from a version before 3.0.0, see the migration instructions in the release notes.

Prerequisites

Before installing the add-on, you need to set up Tailscale:

Create a Tailscale account and install Tailscale on the devices you want to open your sites from (phone, tablet, or another computer), following the installation guide.
Enable HTTPS by following the Tailscale HTTPS documentation. This is required for TLS certificate generation.
Generate an auth key by following the Tailscale auth keys documentation. Ephemeral, reusable keys are recommended. You can also skip the key and log in from your browser after installing the add-on, as described below.

Installation

To get started, follow these steps:

First, set up your auth key (recommended approach): Store the key in the project itself, in .ddev/.env.web.local. DDEV loads that file into the web container only, and it is not committed to Git by default, so the key stays with this project:
```
ddev dotenv set .ddev/.env.web.local --ts-authkey=tskey-auth-your-key-here
```
The shell environment route from the first version of this post still works: if TS_AUTHKEY is exported in your shell (from ~/.bashrc, for example), the add-on picks it up from there. I no longer recommend it as the default. The key ends up in every shell session on the machine, and a shell that does not load ~/.bashrc will not have it when you run ddev.

Alternatively, skip the key and use interactive authentication: run ddev tailscale login after your project starts, and log in from your browser.

Next, install the add-on:

ddev add-on get atj4me/ddev-tailscale-router

Finally, restart DDEV:
```
ddev restart
```

Using Your Tailscale URL

Once installation is complete, you need to start sharing your project:

Start sharing your project:

ddev tailscale share

Launch your project’s Tailscale URL in browser:

ddev tailscale launch

Get your project’s Tailscale URL:

ddev tailscale url

Your project’s permanent Tailscale URL will look like: https://<project-name>.<your-tailnet>.ts.net. You can also find it in your Tailscale admin console.

To see all available commands and options, run ddev tailscale help. This will show you both the DDEV-specific shortcuts and all native Tailscale CLI commands that you can use.

Public vs. Private Mode

The add-on offers two modes for sharing your project:

Private (default): Your project is only accessible to devices on your Tailscale network.
Public: Your project is accessible to anyone on the internet.

To switch between modes:

Share publicly (accessible to anyone on the internet):

ddev tailscale share --public

Share privately (default, only accessible to your Tailscale devices):

ddev tailscale share

Here is what share prints. The QR code works the same way as the one in ddev share: scan it to open the site on your phone instead of typing the address.

$ ddev tailscale share
Starting Tailscale serve on port 80...
Available within your tailnet:

https://demo.your-tailnet.ts.net/
|-- proxy http://127.0.0.1:80

Serve started and running in the background.
To disable the proxy, run: ddev tailscale stop

🔒 Your site is shared privately within your Tailscale network

Scan to open on your phone:
█████████████████████████████
██ ▄▄▄▄▄ █▀█▀▄▀▄▀▀██ ▄▄▄▄▄ ██
██ █   █ █▀▄▀ ▀▀ ▀▀█ █   █ ██
██ █▄▄▄█ █▀ ▀▄▄█ ▀ █ █▄▄▄█ ██
██▄▄▄▄▄▄▄█▄▀ ▀ █▄▀ █▄▄▄▄▄▄▄██
██▄▄ ▄ ▀▄ ▄▀ ▀█▄▄▄ ▄█ █▄█ ███
███▄█▄▀ ▄▄█ ▄█▄█▀▄   ▀█▄█▄ ██
██▀ █▀█▄▄█▀ █▀█ ▄█▀▄▄▀▄▀▄ ▄██
██ █ ▄ █▄▀ ▀█▀▄█▀ ▄ ▀  ▄█▄ ██
██▄█▄███▄█▀█    ▄█ ▄▄▄ ▀▄████
██ ▄▄▄▄▄ █▄▀▄█▄█▄█ █▄█ ▀▄▄ ██
██ █   █ █  █▀█ ▄    ▄ ▀ █▄██
██ █▄▄▄█ █ █▀██▄▄▀ ▀█▀▀ ▄█ ██
██▄▄▄▄▄▄▄█▄███▄▄▄▄█▄█▄▄▄▄▄▄██
█████████████████████████████

Stop sharing:

ddev tailscale stop

Note: For public access, you need to configure your Access Control List (ACL) to enable Funnel. See the Tailscale Funnel documentation for details on setting up the required ACL policy.

Uninstalling the Add-on

If you need to remove the add-on from your project:

Stop any active sharing:
```
ddev tailscale stop
```
Remove the add-on:
```
ddev add-on remove tailscale-router
```
Restart DDEV:
```
ddev restart
```

Additional Resources

Here are some additional resources that you might find helpful:

Tailscale: A VPN service that creates a private and secure network between your devices.
Tailscale Download: Installation guide for Tailscale on various platforms.
Tailscale: Enabling HTTPS: Official documentation on enabling HTTPS for TLS certificate generation.
Tailscale Auth Keys: Detailed information about creating and managing auth keys.
Tailscale Funnel: Documentation on enabling public access to your Tailscale services.
Tailscale DNS: DNS in Tailscale
DDEV dotenv: Documentation on managing environment variables with DDEV.
DDEV Docs: Sharing: The official DDEV documentation on how to share your projects.
Medium: My Journey with PHP Dev Environments: A blog post on setting up a PHP development environment.
LinkedIn: The Day My Development Environment Nearly Broke Me: An article on the importance of a reliable development environment.

I hope this add-on helps streamline your development workflow! If you run into any issues or have suggestions for improvements, feel free to open an issue on the GitHub repository.

The original version of this post was written with assistance from Amazon Q and Google Gemini, and a later update used GitHub Copilot (Claude). This update was prepared with my AI agent, Ryan (Muse), which also worked on the add-on changes described here.