beamd_/Docs

Search docs

Search the Beamd documentation

Quick start

Get a local app onto a public HTTPS URL in a couple of commands — on the hosted edge, or on a domain you own.

Beamd turns a locally-running app into a stable, public HTTPS URL — a distinct subdomain per app, built for the way you (and your agents) actually work. One command in, one URL out:

beamd open 3000 --as api
# → https://api.beam.example.com

There are two ways to get that URL. Pick the one that fits — the developer commands are identical either way.

Fastest — use the hosted edge

No server, no DNS. Install the CLI, log in through your browser, and open a port:

npm i -g @beamd/cli
 
beamd login                  # opens your browser; your edge + scope are assigned automatically
beamd open 3000 --as api     # → https://api-acme.beamd.run

The public URL folds your org into the subdomain — https://<name>-<org>.beamd.run (here, scope acme). Beamd prints it for you; open it or hand it to your agent. Press Ctrl-C to stop the tunnel. That's the whole loop.

Your own domain — self-host

Run one binary on a server with a public IP and point a domain at it. You hand out tokens; tunnels live on your domain.

# on the server (one-time, ~10 min) — see the Setup walkthrough
npm i -g @beamd/cli
sudo beamd serve            # reads /etc/beamd/beamd.yaml automatically
 
# on your laptop
npm i -g @beamd/cli
beamd login --server beam.example.com --token <token-from-operator>
beamd open 3000 --as api     # → https://api.beam.example.com

The full server-side setup — DNS, certificates, onboarding developers — is in the Setup walkthrough. Start with the Self-hosting overview if you want the lay of the land first.

How a tunnel behaves

  • Foreground by default, like ngrok — the tunnel lives until you Ctrl-C. Add -d / --detach to hand it to a background agent and get your prompt back, then manage it with beamd list, beamd status, and beamd close.
  • Stable names. The subdomain is the port by default; --as <name> sets it explicitly, and --from repo|branch|dir derives it from your project.
  • Survives network blips. The client reconnects and replays your tunnels.
  • Machine-readable. Add --json to open / list / close / status for exactly one object of output — ideal for scripts and agents.

Next steps