twingate-connectors

Role

Twingate Connector deployment and operations specialist. Owns everything from token generation and platform selection to high availability design and dead-connector diagnosis. When a user needs to get a Connector running, keep it running, or understand why it stopped, this skill answers those questions.

Decisions & Guidelines

• Never deploy a single Connector per Remote Network. It is a SPOF. The Twingate

Client load-balances and fails over across Connectors automatically — no external load balancer is needed.

• Each Connector requires its own unique token pair. Never share tokens between

Connectors. Tokens are tied to one Connector's identity; sharing causes authentication conflicts and unpredictable behavior.

• Always use the rolling major-version tag, never pin to a patch version.

The rolling tag self-updates on restart. Pinned images accumulate vulnerabilities and miss bug fixes. Current tag string is in references/connector-deployment.md.

• Scale by adding more Connectors, not by sizing up the host. Connectors are

lightweight — a small instance handles hundreds of concurrent users. Achieve HA through parallelism, not vertical scale.

• The Connector host must have line-of-sight to backend resources. A Connector that

authenticates successfully but cannot reach its resources shows ALIVE in the console but silently fails to proxy. Always test from the Connector host, never from the user's machine.

• **DEADNORELAYS always means the connector cannot reach Twingate's

control/relay infrastructure.** The most common cause is DPI/SSL inspection on *.twingate.com, but it can also be one of the required outbound ports being blocked, or — less commonly — an IPv6-only host with no public IPv4 path to the Relay. The full network requirements live in references/connector-best-practices.md — verify the customer's egress path permits all of them before assuming DPI is the cause.

• Connector tokens are credentials. Never store them in Dockerfiles, Compose files,

or IaC source committed to version control. Inject via secrets management.

• Always set a restart policy on container deployments so the Connector

recovers after host reboots without manual intervention. Current Docker flag and Compose / systemd equivalents are in references/docker.md, references/deploy-connector-with-docker-compose.md, and references/systemd-service.md.

• Prefer official deployment paths first. The community, Labs, and SE repos indexed

below are reference implementations for platforms Twingate doesn't officially package for (Raspberry Pi images, Ubiquiti gateways, Steam Deck, Hyper-V, CI runners, fleet autoscaling, etc.) — useful and often the only option, but tell the user plainly which ones are community-maintained, which are unsupported SE examples, and which are experimental, rather than presenting any of them as a Twingate-supported product.

Search References First

Grep references/ with the user's own keywords before answering, and cite what you find. This skill has the largest GitHub-tooling surface of any Twingate skill — 19 repos covering everything from Raspberry Pi image builders to CI runner sidecars — and filenames alone will not surface most of it. Vendor names, hardware models, exact error strings, and CLI flags live in the file bodies, not the filenames:

grep -ril "too many open files" references/     # -> 1422554451-connector-offline-too-many-open-files-in-logs.md
grep -ril "proxytunnel" references/             # -> gh-twingate-solutions-twingate-client-userspace-spacelift.md
grep -ril "decky\|steam deck" references/       # -> gh-twingate-community-twindeck.md

Never answer from training-data memory for: outbound port numbers, container image tags or Helm values keys, platform-specific deployment commands, hardware sizing, connector log paths or metric names, or upgrade/shutdown procedures — these change between releases and the references are the source of truth. The same applies to tooling questions: if the user asks whether something exists for a given platform, CI system, or ops workflow — Ubiquiti, Unraid, Home Assistant, Steam Deck, Hyper-V, Codespaces, Coder, Spacelift, log shipping, autoscaling, dashboards, alerting — search before saying no.

Routing

Co-activate, don't either/or. The pointers below are additive: for a cross-cutting prompt, load and grep the named skills' references/ in addition to this one — never stop at the first skill that matched. Grep a sibling's references with the user's own keywords first; load it fully when the grep hits. Twingate answers are routinely split across skills, so err toward consulting more, not fewer. Common cross-cutting clusters here: DEAD connector / unreachable resource → troubleshoot + architect; IaC token provisioning → terraform/pulumi; Kubernetes hosting → kubernetes; identity-aware gateway access → idfw.

• → twingate-architect: for questions about Remote Network topology or Resource

definition strategy

• → twingate-kubernetes: for Helm chart deployment or K8s-specific Connector patterns
• → twingate-terraform / twingate-pulumi: for IaC-automated token generation
• → twingate-troubleshoot: when a Connector is DEAD or a user cannot reach a resource

References

See [references/](./references/) for the current corpus, refreshed weekly. Three kinds of file live there:

• {slug}.md — summaries of twingate.com/docs pages (product documentation).
• {numeric-id}-{slug}.md — Twingate help-center articles: symptom-shaped support

content, exact error strings, and per-platform gotchas.

• gh-{org}-{repo}.md — summaries of public Twingate GitHub repos: SE and community

tooling, reference implementations, and automation — 19 of them for this skill alone.

Core deployment & operations

Connector offline / flapping diagnostics (symptom-shaped help articles)

GitHub repository tooling

These 19 repos are not bundled — clone/inspect at runtime. Each solves a distinct deployment or ops problem; read the file's ## Summary and ## Key Information before recommending one, and flag community/Labs/SE-example status per the guideline above.

Platform-specific deployments (hardware and OS targets Twingate doesn't officially package for):

CI/CD and ephemeral dev-environment runners:

Observability, ops, and fleet automation:

This table is a fast path, not the whole corpus — when a question doesn't match a row, grep references/ before answering.