Skip to main content

Common Scenarios

Quick recipes for typical setups. Replace SECRET_KEY/TUNNEL_ID with your account credentials, or omit --tunnel-id and --secret-key entirely for anonymous mode.

React dev server on port 3000​

cruma http 127.0.0.1:3000 --tunnel-id react-dev --secret-key SECRET_KEY
  • Start your dev server (npm start/yarn start), then run the tunnel.
  • If your dev server uses HTTPS, use the https subcommand instead of http.

API server on port 8080 with custom domain​

tunnel_id: "api-demo"
tunnel_secret: "SECRET_KEY"

targets:
  - destination: "127.0.0.1:8080"
    kind: http
    hostnames:
      - "api"
      - "api.dev.yourdomain.com"

Run it:

cruma start ./cruma.yaml
  • CNAME api.dev.yourdomain.com to <tunnel-id>.tun.cruma.io, then add it to the hostnames list.
  • api expands to api.<tunnel-id>.tun.cruma.io.

Multi-target config file​

Use a config file to run multiple targets with one command:

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

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

Run it:

cruma start ./cruma.yaml

High-assurance (pinning/mTLS)​

  • Use a custom hostname (CNAME to <tunnel-id>.tun.cruma.io) and terminate TLS on your agent.
  • Pin your agent’s public key in clients (or use mTLS) so only your cert is accepted.
  • Combine with CAA on your domain to restrict certificate issuance to your chosen CA.

Serve a local directory​

cruma serve ./public --allow-dir-index --render-markdown --tunnel-id YOUR_TUN_ID --secret-key SECRET_KEY
  • Add --allow-dir-index to enable directory listing when no index file is present.
  • Add --render-markdown to render index.md (and other .md files) as HTML.
  • You can add simple auth with --user USERNAME PASSWORD or --api-key X-API-Key secret123.