chan
Skip to content

CHAN-GATEWAY / SELF-HOSTED ACCESS

Always-on environments.
Your domain.

Provision managed devservers with your team's tools and a personal access token (PAT). People sign in with OAuth2 and reach their environment from Chan Desktop or a browser, without ssh.

Devservers dial out. People sign in.
YOUR DEVICEDesktop / browserSign in, select a devserver,
open its windows
HTTPS +
WebSocket
YOUR DOMAINGateway proxyChecks access and
forwards traffic
Devserver opens
a TLS tunnel
MANAGED MACHINESChan devserversYour tools + runtime + PAT

After admission, data flows both ways through the tunnel. Files and processes live on the devserver; their traffic passes through your gateway. Access grants cover a devserver's entire library. Read the gateway design doc →

  • Always on.Keep builds, agents, and shells running on managed hosts. Disconnect your client and return to your work.
  • OAuth2, without ssh.Manage access through accounts, devserver grants, and tokens.
  • Provision once.Prepare tools and dependencies on each host. Its PAT connects it to your gateway.
  • Scale the proxy fleet.Add proxy nodes as usage grows. Terminal and file traffic bypasses the central controller.

01 / INTEGRATION POINTS

Sign-in, access, and traffic.

The gateway's account and control services.
OAUTH2GitHub / Google / GitLabYour configured sign-in providers
Sign-in
IDENTITYAccounts & entrygw.example.com
Access checks
PROFILE + POSTGRESUsers & grantsPolicy and audit records
IDENTITY / PROFILE / ADMINPolicy & operations
Inventory +
revocation
DEVSERVER-CONTROLFleet coordinationAdmission and proxy directory
Metadata +
commands
DEVSERVER-PROXYTunnels & trafficOne or more proxy nodes

Identity also stores account sessions in Postgres. Workspace traffic travels through the proxy; the controller carries only metadata and commands. Internal APIs stay private.

02 / CONTROL PLANE

Access is an operational control.

ADMISSION CONTROL

Decide what connects.

Set per-user devserver limits, suspend access, and pause fleet admissions. Every tunnel passes signed admission checks.

ACCESS POLICY

Keep authority in one place.

Manage enrolment, devserver grants, and PATs. Durable policy and audit records live in Postgres.

LIVE SWITCHES

Act on running connections.

Inspect proxies and tunnels, revoke sessions, or pause the fleet with fleet pause --drain. A drain disconnects active sessions and tunnels; resume reopens admission.

chan-gateway-admin fleet status
chan-gateway-admin proxy ps
chan-gateway-admin tunnel ps

Work runs on the devservers independently of client connections. Proxy nodes scale the data path; a singleton controller coordinates admission and policy. On loss of control connectivity, admission stops and existing tunnels close after a bounded grace period. See the scaling and recovery design and operator commands.

03 / SETUP

Bring your domain.

Start with one proxy node, p1. These example names show the DNS and TLS boundaries.

gw.example.com
Sign-in, accounts, and desktop discovery.
p1.proxy.example.com
Proxy node and outbound tunnel ingress.
*.p1.proxy.example.com
A separate origin for each devserver.
  1. 01

    Deploy the services and database.

    Run identity, profile, devserver-control, devserver-proxy, and Postgres. Configure distinct service credentials and signing keys. Apply the database schema jobs before starting runtime services. Use the deployment guide and manifests.

  2. 02

    Connect DNS, TLS, and OAuth.

    Point the names above to your TLS edge and configure a sign-in provider. Route account requests to identity, tenant HTTP/WebSockets to the proxy, and /v1/tunnel to its HTTP/2 ingress. Keep internal listeners on loopback or an authenticated, encrypted private network.

  3. 03

    Provision tools and publish the devserver.

    Enrol users and grant the sign-in and devserver feature flags, which default to off. Install Chan and your team's tools on each managed host. Create a PAT with the tunnel scope in your gateway and supply it as CHAN_TUNNEL_TOKEN on the devserver. Then run:

    chan devserver run \
  --tunnel-url https://p1.proxy.example.com/v1/tunnel \
  --tunnel-devserver-name build-host

    Each devserver uses its own token. The token identifies that devserver's registration.

  4. 04

    Add your gateway to Chan.

    In Computers, press g to open Gateways. Choose Add gateway, enter https://gw.example.com, connect, and sign in. Return to Computers to open owned and shared devservers.

The gateway design explains the architecture. The service documentation covers configuration, and the enrolment guide covers first sign-in.