Skip to main content

Identity and Profiles

Cruma uses a cached identity (keypair) to determine your tunnel’s assigned FQDN. This keeps your URL stable across restarts and avoids conflicting state if two agents try to use the same identity at once.

Profiles​

Use profiles when you want multiple stable identities:

  • --profile <id> (or profile: <id> in config) scopes the cache to a separate directory, giving that profile its own stable identity and FQDN.
  • Profiles are independent, so you can run multiple agents concurrently as long as each uses a different profile.

Multiple agents and config files​

The default config file is just a convenience. You can run multiple agents on the same machine by pointing each agent at a different config file and profile.

Example:

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

Use this pattern when you want separate tunnel credentials or distinct target sets per agent. If you only need one agent with multiple services, prefer a single config file with multiple targets.

Temporary identity​

If you want a fresh FQDN every run, use --temp (or temp: true in config). This creates a one‑off identity and does not persist it to disk.

Why we lock​

The agent holds an OS-level lock on the profile’s cache directory for the lifetime of the process. This is a safety feature that prevents two processes from using the same keypair concurrently, which can lead to confusing behavior and race conditions.