core-relay

Reverse-tunnel relay for CORE gateways. Lets a corebrain CLI on a user's machine expose its local gateway daemon at https://<gateway-name>-<8char>.gw.getcore.me without the user installing Tailscale, ngrok, or any external tunnel client.

Architecture

• Caddy terminates TLS for *.gw.getcore.me (wildcard cert via GoDaddy DNS-01)
• relay is a single Node process with two listeners:
  • :8080 — HTTP forwarder. Routes incoming requests by subdomain to the right WS.
  • :8081 — WebSocket server. Gateway CLIs open one outbound WS to register.
• Auth: on WS connect, relay calls app.getcore.me/api/v1/me with the CLI-supplied PAT. Result cached for 5 minutes.

Local development

npm install
CORE_API_URL=http://localhost:3000 npm start
npm test

Deploy (single EC2)

1. Provision an EC2 t3.medium (Amazon Linux 2023) with an Elastic IP.

2. Open ports 80 + 443 to 0.0.0.0/0, port 22 only to your IP.

3. In the GoDaddy DNS panel, add A records:

   • relay.gw → <EIP>
   • *.gw → <EIP>

4. Generate a GoDaddy API key+secret at https://developer.godaddy.com (Production).

5. On the EC2 box:

   sudo mkdir -p /opt && sudo git clone <this-repo> /opt/core-relay
   sudo cp /opt/core-relay/.env.example /opt/core-relay/.env
   sudo $EDITOR /opt/core-relay/.env   # fill in GODADDY_API_TOKEN
   sudo /opt/core-relay/deploy/install.sh

6. Verify:

   curl -i https://relay.gw.getcore.me/  # expect 502 (no WS connected yet) — TLS handshake should succeed

Operations

• Logs: sudo journalctl -u core-relay -f
• Restart: sudo systemctl restart core-relay
• Update: cd /opt/core-relay && sudo git pull && sudo systemctl restart core-relay

CI / Images

Every push to main builds both images and pushes to GHCR via .github/workflows/build-and-push.yml:

• ghcr.io/<owner>/core-relay:{latest,sha-<short>,vX.Y.Z}
• ghcr.io/<owner>/core-caddy:{latest,sha-<short>,vX.Y.Z}

The workflow uses the built-in GITHUB_TOKEN for GHCR auth — no extra secrets needed. Tests gate the image build (npm test must pass before push). PRs build the images but don't push.

Both images target linux/amd64. Add linux/arm64 to platforms: in the workflow if you switch to a Graviton instance.

Wire protocol

JSON-over-WebSocket. Message types in src/protocol.js. Binary chunks travel as base64.