Asyx CLI

Secure, device-bound tunnels for HTTP, TCP, and UDP. The CLI handles device auth, JWT refresh, and resilient control-plane connectivity so you can expose local services without managing relay infrastructure.

Beta access is invitation-only while we scale capacity.

0. Install & Update

npm install -g asyx          # install
npm update   -g asyx          # upgrade
npm uninstall -g asyx         # remove

• Node.js 18.17+ recommended. Prefer npx asyx <cmd> if you cannot install globally.

1. Set up the device (once per host)

asyx setup

• Opens a browser for passwordless approval and lets you choose <subdomain>.tunnel.asyx.ai.
• Provisions a device certificate and client ID under ~/.asyx/certs/<clientId>/.
• Hardware fingerprint is hashed locally; raw attributes never leave the device.
• Certificates are single-device; run asyx setup on each host.

2. Open tunnels

All tunnels are loopback-only. The CLI never binds your app port; it forwards to your existing listener. Public port comes from your tenant’s 10-port block (auto-assigned unless you request one with --external-port).

HTTP

asyx tunnel --http --port 3000

• Forwards HTTP traffic to 127.0.0.1:3000.
• Forward-only proxy; automatic JWT refresh.

TCP

asyx tunnel --tcp --port <targetPort> [--name <alias>] [--external-port <publicPort>]

• For raw TCP services (databases, SSH, games).
• --port: local app port on loopback.
• --name (optional): CNAME alias <name>.<subdomain>.tunnel.asyx.ai; otherwise use fqdn:publicPort.
• --external-port (optional): must be inside your tenant block; otherwise rejected.
• Uses tcpWs transport; guests connect with native TCP on the public port.

UDP

asyx tunnel --udp --port <targetPort> [--external-port <publicPort>]

• For UDP services (games, realtime apps).
• --port: local app port on loopback.
• --external-port: optional request within your tenant block.
• CLI uses an ephemeral socket; it never claims your service port. Forwards to your app.
• Loopback-only is enforced by CLI and relay.
• Uses udpWs transport; guests send native UDP to the public port.

Minecraft (shortcut)

asyx tunnel --minecraft [--port <localPort>] [--name <alias>]

• One command to share a Minecraft server (defaults to 25565).
• SRV record created so players use the hostname only (no port needed).

After a tunnel opens, the CLI prints:

• fqdn and fqdn:publicPort for guests.
• Target shown as tcp://127.0.0.1:<port> or udp://127.0.0.1:<port> so you know your app keeps the port.

3. Command quick reference

asyx setup                              # Provision device cert & client ID
asyx tunnel --http --port <n>           # HTTP tunnel
asyx tunnel --tcp --port <n> [--name <alias>] [--external-port <p>]
asyx tunnel --udp --port <n> [--external-port <p>]
asyx tunnel --minecraft [--port <n>] [--name <alias>]

• Targets are loopback-only; non-loopback hosts are rejected.
• --external-port must be inside your assigned block; omit to auto-assign blockStart.

4. Protocol details (high level)

• Transport: TCP/UDP tunnels use WebSocket to the relay (tcpWs/udpWs); guests see native TCP/UDP on the public port.
• Assignments: Coordinator returns fqdn, publicPort, relayUrl, and JWT. CLI validates JWT via JWKS before connecting.
• Aliases & SRV: TCP can create CNAME aliases via --name; Minecraft auto-provisions SRV so players use the hostname only.
• Loopback-only: CLI validates; relay enforces at admission/binding. Targets must resolve to loopback.
• Owner-only auth: HTTP can use Quickpass groups; TCP/UDP are owner-authenticated via JWT (no per-guest auth in v4.1).

Quickpass (HTTP guest access control)

• Passwordless guest access: invite guests into a security group and run asyx tunnel --http --port <n> --secgroup <slug>.
• Relay-enforced: guests must present a valid Quickpass cookie; unauthorized requests are rejected at the relay (no app changes).
• Perfect for sharing dashboards/dev tools without opening them publicly; no VPN, no basic auth.
• Zero extra infra: no DNS edits, no reverse proxies; the relay does the policy check.
• Coming extensions: the same flow will back future sharing for TCP/UDP when per-guest auth is added.
• TCP/UDP today remain owner-only via JWT (no per-guest auth in v4.1).

5. Logging

Set verbosity with ASYX_LOG_LEVEL (error|warn|info|debug, default info):

ASYX_LOG_LEVEL=debug asyx tunnel --tcp --port 25565

Structured logs go to stdout/stderr; user banners remain.

6. Behavior notes

• Short-lived JWTs with in-band refresh; tunnels stay up without reconnecting.
• MQTT/JWT control plane is shared across HTTP/TCP/UDP.
• CLI never binds your app port (TCP/UDP); it forwards to it.
• Loopback-only enforcement at both CLI and relay.
• Idle/heartbeat handled automatically; no tuning needed.

7. Why Asyx

• Device-bound identity: Each setup issues a unique cert + uuLID per host; backend rejects duplicates to prevent credential reuse.
• Hardware attestation without PII: Fingerprint is hashed locally from safe fields; raw hardware data never leaves the device.
• Resilient control plane: In-band JWT refresh, bounded reconnects, and structured logs (ASYX_LOG_LEVEL, ASYX_DEBUG) keep long sessions stable.
• Zero manual relay config: Assignments route traffic for you—no DNS edits, firewall poking, or relay setup.
• Multi-protocol, one system: HTTP, TCP, and UDP share the same assignment/JWT/MQTT fabric; pick the protocol that fits your service.
• Secure proxy architecture: Forward-only; avoids local port conflicts and isolates your app from the CLI process.
• Observability-first UX: Clear errors, deterministic exits, optional debug traces.
• Future-ready auth: Today’s magic-link flow extends to sharing via Asyx Quickpass (passwordless downstream approvals).

7. Troubleshooting (quick)

• External port rejected: ensure --external-port is inside your 10-port block.
• Relay unavailable: check network/WSS reachability; see logs for ...RELAY_UNAVAILABLE.
• No traffic to app: confirm your service is listening on 127.0.0.1:<port> and the tunnel is active; for UDP ensure the WS is still connected.
• Windows MQTT handshake issues: rerun asyx setup to regenerate keys (PKCS#1).

8. Security (brief)

• Device-bound identity per host; hardware fingerprint hashed locally.
• Mutual TLS to control plane; RS256 JWTs validated via JWKS.
• Forward-only proxy: your app remains isolated; no direct inbound to your host.
• Report issues: [email protected] (no public issues for security).

9. License

Apache-2.0