docs

Documentation Index

Complete documentation for ts-plug and ts-unplug.

Core Guides

ts-plug Guide

Complete guide for exposing local services to your tailnet.

Topics covered:

• Basic usage and configuration
• HTTP, HTTPS, and DNS proxying
• Public access with Tailscale Funnel
• Security features and user identity headers
• Advanced patterns and troubleshooting

Quick start:

ts-plug -hostname myapp -- python -m http.server 8080

---

ts-unplug Guide

Complete guide for accessing remote Tailscale services locally.

Topics covered:

• Basic usage and configuration
• Development workflows with remote services
• Port mapping and proxy setup
• Security considerations
• Advanced patterns and troubleshooting

Quick start:

ts-unplug -dir ./state -port 8080 myserver.tailnet.ts.net

---

Use Cases

Real-world scenarios and patterns for using ts-plug and ts-unplug.

Scenarios covered:

• Development workflows (full-stack, microservices, mobile)
• Testing scenarios (webhooks, E2E, load testing)
• Deployment patterns (containers, homelab, demos)
• Team collaboration (code review, pair programming)
• Hybrid cloud architectures

Examples:

• Developing locally with remote databases
• Microservices development
• Webhook testing
• Sidecar-free container deployment

---

Docker Integration

Using ts-plug to eliminate Tailscale sidecar containers.

Topics covered:

• Building Docker images with ts-plug
• Real-world examples (Pi-hole, web apps, APIs)
• Docker Compose patterns
• Kubernetes integration
• Best practices and troubleshooting

Quick example:

COPY ts-plug /usr/local/bin/
ENTRYPOINT ["ts-plug", "-hostname", "myapp", "--"]
CMD ["npm", "start"]

---

Quick Reference

When to Use Which Tool

Scenario	Tool	Command
Share local dev server	ts-plug	ts-plug -hostname dev -- npm start
Access remote database	ts-unplug	ts-unplug -dir ./state -port 5432 db.ts.net:5432
Test webhooks	ts-plug	ts-plug -public -hostname webhook -- ./server
Test against staging	ts-unplug	ts-unplug -dir ./state -port 8080 api-staging.ts.net
Deploy in container	ts-plug	Use as Docker ENTRYPOINT
Multi-cloud access	ts-unplug	Multiple instances for each service
Route through remote proxy	ts-unplug	ts-unplug -dir ./state -port 8888 proxy.ts.net:3128

Common Flags

Flag	ts-plug	ts-unplug
Hostname	-hostname myapp	-hostname myproxy
State dir	-dir .data (default)	-dir ./state (required)
Port	-https-port 443:8080	-port 8080
Protocol	-http, -https, -dns	HTTP only
Public	-public	N/A
Debug	-log debug	-debug-tsnet

Getting Started

make                    # Build both binaries
make install            # Install to $GOPATH/bin

Try ts-plug:

./build/ts-plug -hostname test -- python -m http.server 8080

Try ts-unplug:

./build/ts-unplug -dir ./state -port 8080 someservice.yournet.ts.net

Navigation

By Task

• Share dev work → ts-plug Guide → Team Collaboration
• Access remote DB → ts-unplug Guide → Development Workflows
• Test webhooks → ts-plug Guide → Testing Scenarios
• Deploy containers → Docker Guide → Deployment Patterns
• Multiple services → Use Cases

By Role

Developers:

• Start with ts-plug Guide
• Read Development Workflows
• See Team Collaboration

DevOps/SRE:

• Start with Docker Guide
• Read Deployment Patterns
• See Hybrid Cloud

QA/Testing:

• Start with ts-unplug Guide
• Read Testing Scenarios
• See Webhook Testing

Additional Resources

• Main README - Project overview and quick start
• Examples - Sample servers in multiple languages
• Docker Examples - Real container deployments
• ts-plug Source - Implementation details
• ts-unplug Source - Implementation details

Contributing

Found an issue or have a suggestion? Please check the main README for contribution guidelines.

License

BSD-3-Clause - See LICENSE