feat: Tailscale remote-access profile for secure smartphone-to-container connectivity#127
feat: Tailscale remote-access profile for secure smartphone-to-container connectivity#127
Conversation
Co-authored-by: devartifex <21122751+devartifex@users.noreply.github.com> Agent-Logs-Url: https://github.com/devartifex/copilot-unleashed/sessions/dc6a632d-bfa9-4b34-9556-adce10db7627
github-actions
bot
added
documentation
- docker-compose.remote.yml: restrict port binding to 127.0.0.1 to prevent LAN devices from spoofing X-Forwarded-For and bypassing rate limiting when TRUST_PROXY=1 is active - Caddyfile: change admin bind from 0.0.0.0:2019 to localhost:2019 to prevent exposing Caddy's runtime config API to the network - Caddyfile: move header_up directives inside reverse_proxy blocks; they are subdirectives of reverse_proxy in Caddy v2, not site-level directives — the previous placement caused a parse error on startup Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The remote-access profile uses Tailscale Serve for TLS termination — no Caddy container is wired into any compose file. The Caddyfile was documented as optional but contained syntax errors (header_up at site scope, admin on 0.0.0.0) and added confusion without adding value. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds an optional “remote” Docker Compose profile to expose the locally running app securely over Tailscale (WireGuard mesh) with Tailscale Serve providing HTTPS, plus minimal server-side proxy-awareness and supporting docs/scripts.
Changes:
- Add
tailscalesidecar service under aremotecompose profile and adocker-compose.remote.ymloverride for production/proxy settings. - Add a Tailscale entrypoint script that generates a Serve config from
TS_DOMAIN. - Add remote-access documentation and
.env.exampleentries; updateserver.jsto enable forwarded-header handling whenTRUST_PROXY=1.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| server.js | Adds TRUST_PROXY=1 behavior to configure adapter-node forwarded IP handling before importing the built handler. |
| docker-compose.yml | Introduces tailscale sidecar service under the remote profile and a new persistent volume for Tailscale state. |
| docker-compose.remote.yml | Overrides the app service for remote mode (production, localhost-only port bind, BASE_URL, TRUST_PROXY). |
| scripts/tailscale-entrypoint.sh | Generates a Tailscale Serve JSON config at startup when TS_DOMAIN is set. |
| docs/REMOTE-ACCESS.md | Step-by-step guide for two-phase setup (bootstrap + HTTPS) and operational/security notes. |
| .env.example | Documents new Tailscale-related env vars used by the remote profile. |
| This guide explains how to securely access your locally-running **Copilot Unleashed** | ||
| container from a smartphone (or any device) **anywhere in the world** — without opening | ||
| firewall ports, without a static IP, and without Azure. | ||
|
|
||
| The approach uses **Tailscale** (a WireGuard-based VPN mesh) with its built-in | ||
| **HTTPS/TLS serving** capability. Tailscale handles WireGuard encryption, TLS | ||
| termination, and Let's Encrypt certificate provisioning automatically. | ||
|
|
There was a problem hiding this comment.
PR description mentions adding an optional Caddyfile, but there’s no Caddyfile in this PR. Either add it as described or remove the reference from the PR description to avoid confusion for users following the docs.
| echo " Then set TS_DOMAIN and BASE_URL in .env and restart." | ||
| exec /usr/local/bin/containerboot | ||
| fi | ||
|
|
There was a problem hiding this comment.
The serve config is generated directly from TS_DOMAIN without validation. A common mistake is setting TS_DOMAIN to a full URL (e.g. including https://) or adding a trailing slash, which will produce an invalid serve config. Consider validating TS_DOMAIN is a bare hostname (no scheme/port/path) and failing with a clear error message.
| # Validate TS_DOMAIN is a bare hostname (no scheme, port, or path). | |
| case "$TS_DOMAIN" in | |
| *://*|*/*|*:* ) | |
| echo "[tailscale-entrypoint] ERROR: TS_DOMAIN must be a bare hostname (no scheme, port, or path)." | |
| echo " Current value: '$TS_DOMAIN'" | |
| echo " Example: copilot-unleashed.tail1234.ts.net" | |
| exit 1 | |
| ;; | |
| esac |
| // Set automatically by docker-compose.remote.yml for the remote-access profile. | ||
| if (process.env.TRUST_PROXY === '1') { | ||
| process.env.ADDRESS_HEADER = 'X-Forwarded-For'; | ||
| process.env.XFF_DEPTH = process.env.XFF_DEPTH || '1'; |
There was a problem hiding this comment.
The comment says TRUST_PROXY enables trusting X-Forwarded-Proto, but the code only configures ADDRESS_HEADER / XFF_DEPTH. Either remove the X-Forwarded-Proto mention or also set the adapter-node env var(s) needed for protocol forwarding so the comment matches actual behavior.
| process.env.XFF_DEPTH = process.env.XFF_DEPTH || '1'; | |
| process.env.XFF_DEPTH = process.env.XFF_DEPTH || '1'; | |
| process.env.PROTOCOL_HEADER = process.env.PROTOCOL_HEADER || 'X-Forwarded-Proto'; |
| # ────────────────────────────────────────────────────────────────────────── | ||
|
|
||
| tailscale: | ||
| image: tailscale/tailscale:latest |
There was a problem hiding this comment.
Using tailscale/tailscale:latest makes the remote-access profile non-reproducible and can break unexpectedly on upstream releases. Consider pinning to a specific (known-good) Tailscale image tag (and optionally documenting how/when to bump it).
| image: tailscale/tailscale:latest | |
| image: tailscale/tailscale:v1.70.0 # pinned; bump only after verifying new Tailscale releases |
| - TS_USERSPACE=false | ||
| volumes: | ||
| - tailscale-data:/var/lib/tailscale | ||
| - ./scripts/tailscale-entrypoint.sh:/entrypoint.sh:ro |
There was a problem hiding this comment.
/dev/net/tun is currently added via a bind mount under volumes. For TUN access, Docker Compose typically uses a devices: mapping so permissions and device semantics are correct across environments. Switching to devices: - /dev/net/tun:/dev/net/tun will make the sidecar more reliable.
| - ./scripts/tailscale-entrypoint.sh:/entrypoint.sh:ro | |
| - ./scripts/tailscale-entrypoint.sh:/entrypoint.sh:ro | |
| devices: |
| # BASE_URL must be the full HTTPS URL of your Tailscale hostname. | ||
| # Set this in your .env file — compose reads it from there. | ||
| # Example: BASE_URL=https://copilot-unleashed.tail1234.ts.net | ||
| - BASE_URL=${BASE_URL:-https://copilot-unleashed.example.ts.net} |
There was a problem hiding this comment.
BASE_URL falls back to a placeholder https://copilot-unleashed.example.ts.net, which can mask misconfiguration and lead to confusing 403 CSRF / WS origin failures in production. Consider making BASE_URL required in this override (fail fast) or removing the default so users must set it explicitly when enabling the remote profile.
| - BASE_URL=${BASE_URL:-https://copilot-unleashed.example.ts.net} | |
| - BASE_URL=${BASE_URL} |
| > **TL;DR** — Complete the one-time Tailscale setup below, then run: | ||
| > ```bash | ||
| > docker compose -f docker-compose.yml -f docker-compose.remote.yml --profile remote up -d --build | ||
| > ``` | ||
|
|
There was a problem hiding this comment.
This doc’s TL;DR and Phase 1 command both include docker-compose.remote.yml, which forces NODE_ENV=production + Secure cookies. In the described bootstrap mode (no HTTPS serving yet), users won’t be able to sign in over plain HTTP, so it’s worth clarifying that Phase 1 is only for device registration (or adjusting the Phase 1 command to omit the remote override until TLS is enabled).
Adds a
remoteDocker Compose profile that enables secure smartphone access to a locally-running container from anywhere — no port-forwarding, no Azure, no static IP. Uses Tailscale (WireGuard) as the VPN mesh with Tailscale Serve for automatic TLS termination and Let's Encrypt cert provisioning.Architecture
Changes
Infrastructure
docker-compose.yml— addstailscalesidecar service underprofiles: [remote]with healthcheck and a custom entrypointdocker-compose.remote.yml(new) — compose override that switchesapptoNODE_ENV=production, correctBASE_URL, andTRUST_PROXY=1; applied only when enabling HTTPS in phase 2scripts/tailscale-entrypoint.sh(new) — generatestailscale serveJSON config from$TS_DOMAINat container startup, thenexecs intocontainerbootas PID 1. Bootstrap mode (emptyTS_DOMAIN) skips serve config so the device registers first and you discover its FQDN before enabling TLSApp server
server.js— whenTRUST_PROXY=1, setsADDRESS_HEADER=X-Forwarded-ForandXFF_DEPTH=1so SvelteKit adapter-node honours the real client IP and HTTPS protocol from Tailscale Serve (needed for rate-limiting, secure cookies, and CSRF)Optional / advanced
Caddyfile(new) — reference config for users who want Caddy as an HTTP-layer proxy on top; not used by the default setupDocs & config
.env.example— documentsTS_AUTHKEY,TS_HOSTNAME,TS_DOMAINdocs/REMOTE-ACCESS.md(new) — full guide: two-phase setup flow, PWA install, push notifications, Tailscale ACLs,ALLOWED_GITHUB_USERS, troubleshootingTwo-phase setup
Phase 1 (bootstrap — no
TS_DOMAINneeded):docker compose --profile remote up -d --build # → device registers; find FQDN at login.tailscale.com/admin/machinesPhase 2 (enable HTTPS after setting
TS_DOMAIN+BASE_URL):docker compose -f docker-compose.yml -f docker-compose.remote.yml \ --profile remote up -d --force-recreate # → Tailscale provisions Let's Encrypt cert, app served over HTTPSType of Change
Testing
npm run test:unit)npx playwright test)docs/TEST-MATRIX.mdif this PR adds or modifies a featureQuality Checklist
npm run checkwith no new errorsnpm run buildsuccessfullyconsole.logor debug code left inSecurity (for public repo)
Screenshots / Recordings
No UI changes. Infrastructure and server-layer only.
Original prompt
execute the plan after creating a dedicated issue containing full plan
**Chronological Review:** 1. User requested a plan for secure smartphone-to-local-container connectivity, noting "maybe not everyone has Azure" 2. Two background explore agents were launched to analyze: (a) networking/security architecture, (b) PWA/mobile support 3. Both agents completed after ~90-97 seconds with comprehensive findings 4. Five clarifying questions were asked via ask_user tool 5. Plan was created and saved to plan.md file 6. 8 todos with 12 dependencies were inserted into SQL tables 7. Plan mode was exited with a summaryIntent Mapping:
Technical Inventory:
Code Archaeology:
Progress Assessment:
Context Validation:
Recent Commands Analysis:
1. Conversation Overview: - Primary Objectives: User asked "how it would be possible to have a very strong and safe connection between my smartphone and the local running container of this solution? Because maybe not everyone has Azure" — seeking a secure remote access plan for the self-hosted Copilot Unleashed app running in Docker - Session Context: Plan-mode session that progressed through codebase analysis → clarifying questions → plan creation → todo tracking → exit to interactive mode - User Intent Evolution: Started with an open question about smartphone connectivity → refined through 5 clarifying questions to: Tailscale sidecar + Caddy in docker-compose, remote access from anywhere, full PWA with push, device-restricted ACLs-
- SvelteKit + adapter-node: App framework, server.js uses
- Docker: Single container,
- PWA: Complete manifest.json (standalone, all icon sizes including maskable), service worker with push support, Apple meta tags — all require HTTPS except on localhost
- Security Stack: CSRF origin check (hooks.server.ts), WS origin validation (ws/handler.ts), secure cookies (
- Auth: GitHub Device Flow (no HTTPS required on app side), AES-256-GCM encrypted auth cookie
- WebSocket: Client builds URL from
- Planned Architecture: Tailscale sidecar (WireGuard VPN) → Caddy (TLS termination with Tailscale-provisioned Let's Encrypt certs) → App (HTTP :3000)
-
- server.js:
- Purpose: Main HTTP/WS server entry point
- Current State: HTTP-only,
- Key Detail: Needs ~2 lines added for
- docker-compose.yml:
- Purpose: Container orchestration
- Current State: Single app service,
- Planned: Add
- src/hooks.server.ts:
- Purpose: CSRF ...
Technical Foundation:
http.createServer()(HTTP only, no TLS), binds0.0.0.0:3000docker-compose.ymlwithNODE_ENV=development,BASE_URL=http://localhost:3000, port mapping3000:3000secure: !isDev), rate limiting (200/15min), CSP headers — all security checks skipped in dev modewindow.location(relative, auto-adapts to any origin), heartbeat with missed ping trackingCodebase Status:
ORIGINdefaults toBASE_URLorhttp://localhost:${port}, no trust-proxy supportTRUST_PROXYenv var to readX-Forwarded-*headers from CaddyNODE_ENV=development,BASE_URL=http://localhost:3000tailscaleandcaddyservices under aremoteprofileCreated from Copilot CLI via the copilot delegate command.
📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.