Skip to content

remote-ssh.md

Latest commit

 

History

History
65 lines (44 loc) · 1.93 KB

remote-ssh.md

File metadata and controls

65 lines (44 loc) · 1.93 KB
Raw

Expose the gateway over SSH

Status: unsupported experimental. These surfaces are source-available but outside the supported v3 product contract. They are hidden from default hack --help (see hack help --all) and print a warning when invoked.

This is a beta workflow. Start with Core docs if you are new to hack, and use Beta workflows for the rest of the remote path.

⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.

Use SSH port-forwarding when you want quick, ad-hoc access without extra tooling. You still need a reachable SSH host (public IP, VPN, or Tailscale).

Steps (one command)

hack remote setup

Choose SSH tunnel when prompted. The wizard enables the gateway, creates a token, and prints the SSH port-forward + QR payload.

Steps (manual)

  1. Enable gateway + create a token:
hack gateway enable
hack daemon stop && hack daemon start
hack x gateway token-create --scope read
  1. Forward the gateway port (from your remote client):
ssh -L 7788:127.0.0.1:7788 <user>@<public-host-or-tailnet>
  1. Verify from the client (127.0.0.1 is your local end of the tunnel):
curl -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" http://127.0.0.1:7788/v1/status

Off-network access

If your machine is not directly reachable, use one of:

  • Tailscale (recommended for SSH): tailscale up --ssh
  • Public IP + router port-forwarding to SSH
  • Cloudflare Access (desktop clients only): see remote-cloudflare.md

Public IP + DNS (optional)

If you want a stable hostname (e.g. ssh.example.com):

  1. Point an A/AAAA record to your public IP.
  2. Forward TCP port 22 on your router to your machine.
  3. Use the DNS name in the SSH command: ssh <user>@ssh.example.com

QR payloads

hack remote qr --ssh --ssh-host <host> --ssh-user <user>

This prints an ssh:// QR payload for mobile clients.