Status: SSH key management is implemented. The SSH gateway is designed here and is not deployed; it needs infrastructure the owner provisions.
Forge serves Git over Smart HTTP from Cloudflare Workers. Developers also
expect git clone git@forge.smol.ai:owner/repo.git, which is how GitHub
clients usually authenticate. This document explains why SSH cannot terminate
in a Worker, what is shipped, and the small gateway that completes the feature.
A Worker receives HTTP requests (and WebSockets upgraded from them). It cannot
listen on TCP port 22 or accept an arbitrary inbound TCP stream. Cloudflare
Containers are reached only through a Worker or Durable Object over HTTP, so
they cannot accept inbound SSH from the internet either. connect() in Workers
is outbound only.
SSH therefore has to terminate in a process that owns a TCP listener, then hand the Git protocol to Forge over HTTP.
user_ssh_keys (migration 0034): one row per public key, with a unique
OpenSSH SHA256: fingerprint, so a key identifies exactly one account (as on
GitHub). last_used_at is stamped on each successful lookup.GET /api/users/me/ssh-keysPOST /api/users/me/ssh-keys with { "title": "Laptop", "key": "ssh-ed25519 AAAA… comment" }DELETE /api/users/me/ssh-keys/:id
Accepted types: ssh-ed25519, ecdsa-sha2-nistp{256,384,521}, the sk-
security-key variants, and ssh-rsa of at least 2048 bits. The stored key
drops the comment; the comment becomes the default title.findActiveUserBySshFingerprint() in
packages/api/src/features/ssh-keys/model.ts: the lookup the gateway uses.git client ──SSH:22──▶ edge TCP proxy ──▶ forge-sshd ──HTTPS──▶ Forge Smart HTTP
(Spectrum or (container (existing
Tunnel) or VM) /owner/repo.git/*)forge-sshd is a small SSH server (for example Go gliderlabs/ssh, or
OpenSSH with AuthorizedKeysCommand and a ForceCommand shim). For each
connection it:
git. It asks Forge to
resolve the offered key's fingerprint. OpenSSH verifies possession of the
private key before the command runs.git-upload-pack '<owner>/<repo>.git' or
git-receive-pack '<owner>/<repo>.git' (plus git-lfs-authenticate, which
returns the existing LFS HTTP endpoint and a temporary token). It refuses
shells, port forwarding, and agent forwarding.createTemporaryRepositoryCredential() (30-minute, single
repository, repo:read/repo:write). Forge's normal permission checks then
apply unchanged.info/refs
with Git-Protocol: version=2 when the client asked for it, then
POST git-upload-pack or git-receive-pack, copying pkt-lines in both
directions. Protocol v2 makes this a clean request-per-command mapping.
Upload-pack v0 needs the same --stateless-rpc framing that git http-backend uses.Forge needs one internal endpoint for the gateway, which this change does not
add: POST /api/internal/ssh/authorize, with { fingerprint, repository, service }. It is authenticated by a gateway secret or a Cloudflare service
binding, and returns { username, token } or 403. It combines
findActiveUserBySshFingerprint, the repository permission check, and
temporary-credential minting. That keeps all authorization in Forge; the
gateway holds no database credentials.
The host key must be stable and its fingerprints published in the docs so clients can verify them on first connect, as GitHub publishes its own.
None of these resources exist yet. Each needs an owner decision and account changes.
| Option | What it needs | Notes |
|---|---|---|
Cloudflare Spectrum (SSH app) on ssh.forge.smol.ai:22 → origin running forge-sshd |
Spectrum on the zone (SSH is supported on paid plans), an origin VM or container host with a public or tunnelled address | Keeps git@forge.smol.ai-style UX if a dedicated hostname is used; DDoS protection included |
Cloudflare Tunnel (cloudflared) from the forge-sshd host + Spectrum or a public TCP route |
A small always-on VM (e.g. 1 vCPU) | No inbound ports on the host |
| Port 22 directly on a VM (no Cloudflare in path) | DNS record for ssh.forge.smol.ai (grey-cloud) |
Simplest; loses Cloudflare edge protection |
forge-sshd is stateless and does little CPU work. Git data streams through
it to Workers, so one small instance per region handles typical use. The
owner also needs to:
FORGE_SSH_GATEWAY_SECRET) in the identity
Worker and the gateway,A Worker could accept SSH tunnelled through a WebSocket (as
cloudflared access ssh does), but every client would need a helper in its
ProxyCommand. That fails the main goal: unmodified git with an SSH remote.