Configuration via file

You can run cruma from a config file instead of passing flags. The CLI accepts YAML or JSON and will validate the structure before starting the tunnel. The agent watches the file and applies changes to credentials and targets automatically.

Helpful commands:

• cruma config locate prints the default config path.
• cruma config init [PATH] creates a new config with ANON credentials and no targets (use --config or PATH to choose a file).
• cruma config reset deletes and recreates the default config.
• cruma config profiles lists known profile IDs and their cache directories.

Minimum fields to set:

• tunnel_id (optional; defaults to ANON)
• tunnel_secret (from your account)
• targets (list of entries with kind, destination, and optional hostnames)
  • kind: http, https, tcp, raw, or local-directory
  • destination: backend address/port (e.g., 127.0.0.1:3000 or example.com:443), or a local directory path for local-directory
  • hostnames: shortnames or full domains that should map to this target

Optional top-level settings:

• tower_server: override the control plane endpoint (default: tower.cruma.io:443)
• profile: use a named profile to scope the cache directory (stable identity per profile)
• temp: use a temporary identity/cache (fresh FQDN each run)

Notes:

• Changes to tower_server, profile, or temp require a restart to take effect.

Example YAML:

tunnel_id: "demo-tunnel"
tunnel_secret: "beta-secret-123"
tower_server: "us-east.cruma.io:443"

targets:
  - destination: "example.com:443"
    kind: https
    hostnames:
      - "api"
      - "api.dev.yourdomain.com"
  - destination: "127.0.0.1:3000"
    kind: http
    hostnames:
      - "react-dev"
      - "react.dev.yourdomain.com"

Run it with:

cruma start ./cruma.yaml

Default config vs. multiple configs

The default config file is just a convenience. You can run multiple agents by pointing each one at a different config file (and a different profile).

cruma start ./configs/app-a.yaml --profile app-a
cruma start ./configs/app-b.yaml --profile app-b

Use multiple configs when you want separate tunnel credentials or distinct target sets per agent. If you only need one agent with multiple services, keep a single config file and add multiple targets.

Directory targets and access controls

Directory targets support optional directory indexing, form-based login, and API key checks. Form auth and API key checks are also available for http and https targets.

targets:
  - destination: "./public"
    kind: local-directory
    hostnames:
      - "static"
    allow_directory_indexing: true
    render_markdown: true
    form_auth:
      users:
        - ["demo", "demo-password"]
      secret: "replace-with-a-random-secret"
    api_key_auth: ["X-API-Key", "secret123"]

Notes:

• Directory targets serve index.html by default when present.
• Set render_markdown: true to render index.md (or other .md files) as HTML.

Lock files, profiles, and multiple agents

Cruma uses a single cached identity per profile to keep FQDNs stable and avoid conflicting state if two agents try to use the same keypair at once. To enforce that, the agent holds an OS-level lock on the profile’s cache directory for the lifetime of the process.

If you want multiple agents at the same time, use profiles:

• --profile <id> creates a separate, stable identity (and therefore a separate stable FQDN) per profile.
• temp: true or --temp uses a one‑off identity for disposable tunnels and avoids writing to the cache.