Skip to main content

Quick Start Guide

This guide should be simple enough to get your locally hosted web-site or service accessible on the public Internet within 1-3 minutes.

What is Cruma?​

Cruma is a local-first tunneling agent that gives you a public URL for local or private services with a single command, plus a TUI and localhost-only web UI for inspection and control. It supports HTTP, HTTPS, TCP, raw TCP, and serving local directories.

If you bring your own domain via CNAME, you can terminate TLS on your agent (or behind your own reverse proxy) for end-to-end encryption; in that mode Cruma only sees control-plane metadata.

Key concepts​

  • tunnel_id defines the public FQDN and routing pool; agents sharing a tunnel ID are load‑balanced together.
  • profile scopes the cached identity (useful for multiple anonymous identities).
  • temp creates a one‑off identity for a fresh FQDN each run.

Accessing the agent​

Cruma is now in public beta. The service is free during this period while features, limits, and pricing evolve based on real‑world use.

Download the tunnel agent at https://cruma.io and pick your platform. On first run you’ll see a TUI-based setup wizard; you can also run cruma --help to see all options.

Install & run (fast path)​

  1. Download the agent from https://cruma.io and install for your OS.
  2. Start your local service (for example on port 3000).
  3. Run:
cruma http 127.0.0.1:3000

Anonymous quick test​

You can run an anonymous tunnel without a tunnel ID/secret. A unique FQDN is assigned and persisted in the agent cache directory (see cruma show-cache; it falls back to .cruma-tunnel-cache if an OS cache dir is unavailable):

cruma http 127.0.0.1:3000

This is great for quick local tests; anonymous tunnels have tighter limits (see Rate Limits & Fair Use).

Anonymous mode is zero‑setup. When you’re ready for custom domains or higher limits, add --tunnel-id and --secret-key from your account.

If you want a fresh anonymous FQDN each run, add --temp. For multiple stable anonymous identities, use --profile <id>.

Basic usage with credentials​

This assumes your service is running locally on port 8080. Replace TUNNEL_ID and SECRET_KEY with the values from your account.

cruma http 127.0.0.1:8080 --tunnel-id TUNNEL_ID --secret-key SECRET_KEY
  • TARGET is the local address and port you want to expose.
  • --tunnel-id is the tunnel name; leave it out to use the default (sourced from your configuration file, otherwise ANON).
  • --secret-key only used in combination with tunnel-id. also sourced from your configuration file or otherwise ANON
  • --tower-server defaults to tower.cruma.io:443; optional override to target a different region.

You’ll receive the public URL after the tunnel is established. Use --headless if you want to disable the interactive terminal UI.

if not provided, these are sourced from your default config file if you have one.

What Cruma is (and isn’t)​

  • Local-first tooling: TUI and localhost web UI; logs stay on your machine.
  • Optional end-to-end TLS when using your own domain.
  • No bundled SSO suite, no complex enterprise policy engine, and no formal SLA.

Choosing a region (optional)​

By default the agent connects to the closest region via tower.cruma.io:443. To pin a region explicitly, pass --tower-server:

cruma http 127.0.0.1:8080 --tower-server us-east.cruma.io:443
cruma http 127.0.0.1:8080 --tower-server eu-fi-hel.cruma.io:443

Using a config file​

If you prefer to manage multiple targets in one place, you can load them from a config file (YAML or JSON) with cruma start ./cruma.yaml. See the configuration guide for an example and the schema.

Forwarding Raw TCP services​

Use raw for TCP services where you want to handle TLS yourself.

cruma raw 127.0.0.1:4943 --tunnel-id TUNNEL_ID --secret-key SECRET_KEY

This creates a raw TCP tunnel; the platform will provide the reachable endpoint once the tunnel is up.