Skip to main content

Multiple Targets and Tunnels

One agent, many targets​

You can expose multiple services from a single agent and tunnel. Use the config file to declare multiple targets and hostnames; you usually do not need separate tunnels for each service on the same machine.

Shared tunnel IDs (important)​

A tunnel ID defines the public FQDN and the routing pool at cruma.io. If you run multiple agents with the same tunnel_id, they all share that same public address and traffic is load‑balanced between them.

This is great for multi‑region or multi‑host deployments as long as the configs are the same across those agents. If configs differ (different hostnames, targets, or auth), routing becomes unpredictable because requests may land on a different agent than you expect.

Rule of thumb: if you need different hostnames/routes/configs, use different tunnel IDs. If you want the same public address served from multiple places, keep the same tunnel ID and keep configs identical.

Profiles are separate from tunnel IDs: profiles only scope the cached identity (useful for anonymous tunnels), while the tunnel ID controls the public FQDN and routing pool.

Example:

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 with:

cruma start ./cruma.yaml

When one tunnel is enough​

  • A few services owned by the same team/environment.
  • Shared credentials are acceptable (same tunnel secret).
  • Simple DNS: one tunnel ID with shortnames or custom hostnames.

When to use separate tunnels​

  • You need different hostnames/routes/configs that should not be load‑balanced together.
  • Isolation per app/team/environment (different credentials and blast radius).
  • Different domains/hostnames that you want to keep apart.
  • Different usage profiles or rate-limit buckets.

Multiple agents for the same tunnel​

You can run multiple agents with the same tunnel ID for load spreading and regional placement. Each agent connects to its nearest Cruma datacenter; callers are routed to the nearest datacenter where that tunnel is connected. Common patterns:

  • Regional presence: one tunnel, agents in EU and US to serve users closest to each region.
  • Simple load sharing: multiple agents behind the same tunnel ID on different servers.

Coordinate credentials and targets carefully when sharing a tunnel across agents. Use distinct tunnels if you need stricter isolation or different routing behavior.