Deploy twingate-template

Twingate Connector — Railway Template

Run a Twingate Connector on Railway: zero-trust, outbound-only access between your Twingate tenant and a private network. No inbound ports, no public domain — the connector dials out to Twingate and stays connected.

This template packages the official twingate/connector:1 image (major tag pinned) with a Railway-friendly wrapper:

• Configure-me state — deploy first, add tokens later. Missing Twingate variables leave the service healthy with step-by-step instructions in the logs (no crash-loop).
• HTTP health shim — Railway healthchecks are HTTP-only, but the connector's native check is the exec command connectorctl health. A tiny in-container shim polls it and serves /healthz on the internal $PORT (200 healthy/starting/configuring, 503 degraded).
• Zero deploy-form prompts — the template provisions instantly; you paste your three Twingate values into service variables after deploy.

What you need before deploying

A Twingate account (the free Starter plan works). In the Twingate Admin Console you will create (or pick) a Remote Network and generate a Connector token pair — about two minutes, done after the deploy if you prefer.

Deploy and Host

Deploy with the button above — one service (twingate-connector) is provisioned from the public repo, healthcheck wired to /healthz, no public domain, no volumes. The first deployment comes up in the healthy configure-me state; the logs print the exact token setup steps.

Then connect it:

1. Sign in to your Twingate Admin Console (https://your-tenant.twingate.com).

2. Open Remote Networks and pick (or create) the network this connector will serve, then click Deploy Connector / +.

3. Choose Docker and copy the three values from the shown command.

4. In Railway, open the service → Variables and add:

   Variable	Value
   TWINGATE_NETWORK	Your network slug only, e.g. acme-co — never a URL
   TWINGATE_ACCESS_TOKEN	Access token shown for this connector
   TWINGATE_REFRESH_TOKEN	Refresh token shown for this connector

5. The service redeploys automatically. Within a minute the connector shows Online in the Admin Console.

About Hosting

A single outbound-only service built from the official twingate/connector:1 binaries plus:

• an entrypoint wrapper that gates the boot on the three Twingate variables (TWINGATE_NETWORK, TWINGATE_ACCESS_TOKEN, TWINGATE_REFRESH_TOKEN) and keeps the container healthy with setup instructions when they are missing;
• a static HTTP health shim that serves /healthz on the assigned $PORT, backed by the connector's native connectorctl health exec check (polled every 30 s; a HEALTH_GRACE_SECONDS grace window, default 300 s, separates "still starting" from "unhealthy").

Important constraints:

• Unique token pair per connector. Every connector instance needs its own pair, generated per connector in the Admin Console. Never reuse a pair on a second connector — Twingate disconnects the first one when the pair connects elsewhere. For high availability, deploy this template a second time and generate a fresh pair for it on the same Remote Network.
• Time-expiring tokens. Generate the pair right before you paste it into Railway. If a stored pair expires, reprovision the connector (new pair) and update the variables.
• Clock skew. Token authentication breaks with more than ~5 seconds of clock skew; Railway hosts are NTP-synced, so this mostly matters if you move the setup elsewhere.
• No volume is needed — connectors are stateless. A 512 MB / shared-vCPU service is ample (~$3–5/month on Hobby).

Why Deploy

• One click instead of a VPS runbook: no Docker host to provision, no systemd unit, no firewall rules — the connector needs only outbound 443.
• Railway-native health reporting: the included shim bridges the connector's exec-only health check to Railway's HTTP healthchecks, so a broken connector surfaces in the dashboard instead of flapping silently.
• Safe to deploy empty: the configure-me state means a fresh deploy never crash-loops; the service waits for you with instructions in the logs.
• Pinned upstream: the image lifts the binaries from twingate/connector:1 (major tag), so updates track the connector-1 line without surprise majors.

Common Use Cases

• Reach a private network from anywhere: put a connector in front of resources your team reaches over Twingate (admin panels, RDP/SSH hosts, internal dashboards).
• Cloud-side connector for a homelab network: pair this Railway connector with a connector inside your home network so Twingate routes between cloud and home without exposing either.
• Fast, disposable access paths: spin up short-lived zero-trust access to a demo or staging network, then tear the service down — cost tracks usage.
• Second connector for HA: Twingate recommends two connectors per Remote Network; deploy the template twice with distinct token pairs.

Dependencies for

None — the connector is a self-contained outbound-only service. It requires no database, no volume, and no inbound ports; it only dials out to Twingate's controller over TLS.

Deployment Dependencies

• A Twingate account with an Admin Console (https://your-tenant.twingate.com); the free Starter plan works.
• Three values from the Admin Console's connector deploy dialog: the Remote Network slug (TWINGATE_NETWORK) and the per-connector token pair (TWINGATE_ACCESS_TOKEN, TWINGATE_REFRESH_TOKEN) — set them as secret variables on the service after deploy.
• Outbound internet access from the Railway region (default and always available on Railway).

Troubleshooting

• Logs repeat authentication/connection errors — tokens invalid, expired, or from a different connector. Generate a fresh pair in the Admin Console and update all three variables (the pair must match the network slug).
• 503 from /healthz — the connector never became healthy within the grace period; check logs for State: Error (invalid/expired tokens are the usual cause).
• Connector flip-flops Online/Offline in the Admin Console — the token pair is used by more than one connector instance; give each instance its own pair.
• Authentication failures on a fresh deploy — clock skew; Railway hosts are NTP-synced, so re-check anything between (rare).