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. Most of this guide is focused on the TUI mode, but the concepts apply also to desktop/gui mode.

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. It comes with a TUI (terminal UI) and a desktop app for inspection and control. It supports HTTP, HTTPS, TCP, raw TCP, serving local directories, and hosting processes.

On paid tier tunnels, TLS is terminated on your agent using a certificate automatically obtained from Let's Encrypt (ACME TLS-ALPN-01). If there are any issues obtaining such a certificate, termination will be handled on cruma.io until the agent has a proper certificate. This process is transparent so that you can clearly see where termination happens. This provides end-to-end encryption between clients and your agent — Cruma infrastructure only forwards the encrypted stream and 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 (config-file setting) scopes the cached identity (useful for multiple anonymous identities).

Accessing the agent​

Download the tunnel agent at https://cruma.io and pick your platform. Starting the application by double-click or without arguments will launch the GUI by default, but it is also possible to start the TUI using "cruma --tui".

Desktop Application (GUI)​

Normally when starting the cruma agent without arguments or when opening from desktop/start-menu etc, the GUI will launch automatically. TUI and Headless mode are opt-in from the command-line.

Note that the remainder of this guide is mostly useful for those who prefer the terminal modes, as the desktop application has built in setup-wizards and is overall easier for new users to start with.

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 proxy http 3000

That's it — you'll get a public URL printed in the terminal.

Anonymous quick test​

You can run an anonymous tunnel without a tunnel ID or secret. A unique FQDN is assigned and persisted in the agent cache directory (see cruma show-cache):

cruma proxy http 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.

For a fresh anonymous FQDN each run, set temp: true in your config file. For multiple stable anonymous identities, set profile: <id> in your config file.

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 proxy http 127.0.0.1:8080 --tunnel-id TUNNEL_ID --secret-key SECRET_KEY
  • The target can be host:port (e.g. 127.0.0.1:8080), just a port number (e.g. 8080, defaults to 127.0.0.1), or a hostname (e.g. example.com).
  • --tunnel-id is the tunnel name; leave it out to use the default (sourced from your configuration file, otherwise ANON).
  • --secret-key is only used in combination with --tunnel-id; also sourced from your configuration file if not provided.
  • --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.

UI modes​

  • By default the agent starts an interactive TUI.
  • Use --headless to disable the interactive terminal UI (useful for scripts and CI).
  • Use --tui to force the interactive TUI (useful when the agent would otherwise default to headless).
  • Use --theme light|dark|system to control the UI theme (system is the default).

Serve a local directory​

You can serve static files from a local directory without any other server:

cruma serve ./public

Options:

  • --allow-dir-index — show directory listing when no index file is present.
  • --render-markdown — render .md files as HTML.
  • --spa — SPA fallback: serve the nearest index.html instead of 404 for missing paths.
  • --user USERNAME PASSWORD — add form-based authentication.
  • --api-key HEADER VALUE — require an API key header.
  • --listen SPEC — add a local listener (e.g. --listen https:8443). Defaults to cruma when omitted.
  • --hostname PATTERN — hostname pattern for routing.
  • --forward-host true|false — forward the original Host header to the backend (default: true).

What Cruma is (and isn't)​

  • Local-first tooling: TUI and desktop app; 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 proxy http 127.0.0.1:8080 --tower-server tower.us-east.cruma.io:443
cruma proxy http 127.0.0.1:8080 --tower-server tower.eu-fi-hel.cruma.io:443

Using a config file​

For multi-target setups, use a config file (YAML or JSON). The config uses backends (where traffic goes) and frontends (hostname routes that point to backends):

tunnel_id: "demo-tunnel"
tunnel_secret: "beta-secret-123"

backends:
  - id: web
    kind: http
    destination: "127.0.0.1:3000"

frontends:
  - hostname: "app"
    backend_id: web

Run it with:

cruma start ./cruma.yaml

You can also manage configs from the CLI without editing YAML by hand:

cruma config add http 127.0.0.1:3000 --hostname app
cruma config show

See the configuration guide for the full reference including processes, listeners, middlewares, and local-only mode.

Forwarding TCP services​

Use proxy tcp to forward plain TCP to your backend after TLS termination:

cruma proxy tcp 127.0.0.1:5432 --tunnel-id TUNNEL_ID --secret-key SECRET_KEY

For assigned FQDNs (*.tun.cruma.io), TLS is terminated at the Cruma ingress until the agent successfully retrieves a certificate using ACME DNS01; this normally only takes a few seconds but can take longer in some cases. The certificate will be automatically refreshed as needed after that. For CNAME'd custom domains, TLS is terminated on your agent using ACME TLS ALPN-01 by default, but you can change this behavior as you wish. Either way, your backend receives a plain TCP stream.

Use proxy raw for TLS pass-through to your backend (the backend handles TLS itself):

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

Note: raw only provides true TLS pass-through when using paid tiers.

The platform will provide the reachable endpoint once the tunnel is up.

Upstream protocol​

When proxying HTTP/HTTPS traffic, you can select the protocol used to talk to your backend with --upstream-protocol:

  • h1 — HTTP/1.1 (default, most compatible)
  • h2 — HTTP/2 (ALPN-negotiated for HTTPS backends, h2c upgrade for HTTP)
  • h2pk — HTTP/2 Prior Knowledge (speak HTTP/2 directly without negotiation)
cruma proxy http 127.0.0.1:3000 --upstream-protocol h2