# Cruma Docs - LLM Guide

Cruma is a local-first tunneling agent (CLI + TUI) that exposes local/private services via public URLs on the cruma.io network.
It supports HTTP, HTTPS, TCP (with TLS termination at Cruma), raw TCP (no TLS termination), and serving a local directory.

Start here (human docs):
- Quick Start Guide
- Configuration via file
- Identity and Profiles
- Multiple Targets and Tunnels

Mental model
- One agent process can serve multiple targets via a config file.
- Multiple agents can run on the same machine if they use different profiles (separate cached identities).
- Anonymous mode: omit tunnel credentials; a stable FQDN is derived from a locally cached identity keypair.
- Authenticated mode: provide tunnel_id + secret_key; the tunnel_id determines the public FQDN label.

Protocol differences (important)
- http: Cruma terminates HTTP at the edge and forwards to your HTTP backend.
- https: Cruma terminates HTTPS at the edge and forwards to your HTTPS backend.
- tcp: Cruma terminates TLS for inbound traffic, then forwards plain TCP to your backend.
- raw: Cruma does NOT terminate TLS; bytes pass through to your backend (you handle TLS yourself).

Common commands
- Show help:       cruma --help
- Completions:     cruma --generate-completions bash
- Nushell:         cruma --generate-completions nushell
- Single HTTP:     cruma http 127.0.0.1:3000
- Single HTTPS:    cruma https 127.0.0.1:8443
- Single TCP:      cruma tcp 127.0.0.1:5432
- Raw TCP:         cruma raw 127.0.0.1:4943
- Serve dir:       cruma serve ./public --allow-dir-index --render-markdown
- Config file:     cruma start ./cruma.yaml
- Config locate:   cruma config locate
- Cache location:  cruma show-cache
- Clear cache:     cruma clear-cache

Config file basics (YAML or JSON)
- Top-level:
  - tunnel_id (optional; defaults to ANON)
  - tunnel_secret (from account)
  - targets (list)
  - tower_server, profile, temp (optional)
- Targets:
  - kind: http | https | tcp | raw | local-directory
  - destination: address:port (or directory path for local-directory)
  - hostnames: shortnames or full domains

Multiple agents on one machine
- Use separate config files and profiles:
  - cruma start ./configs/app-a.yaml --profile app-a
  - cruma start ./configs/app-b.yaml --profile app-b

Notes
- The default config file is a convenience; any path works via `cruma start [PATH]` or `--config` where supported.
- For custom domains, CNAME your hostname to <tunnel-id>.tun.cruma.io and add that hostname to the target.