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.

What's New in 0.4.0

Improved large file downloads: HTTP tunnels now automatically use streaming transport for large responses (8 MiB+ or unknown size). This enables reliable downloads of any size without hitting memory limits or connection timeouts. The switch happens automatically—no flags or configuration needed. Small responses continue to work exactly as before.

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