Skip to main content
On unix platforms (macOS/Linux), aivault invoke connects to a background daemon (aivaultd) over a unix socket. Secret decryption and auth injection happen inside the daemon process, not the CLI process — adding an extra isolation layer.

​
Why this exists

The daemon boundary is an extra hardening step for agent-heavy environments:
  • The CLI stays a thin client that sends an invocation envelope.
  • Decryption + auth injection happen in the daemon process, not the caller process.
  • Operational flexibility: you can run the daemon under a different execution context later (different user, tighter filesystem permissions, supervisor-managed lifecycle), without changing the invoke contract.

​
How it works

The CLI process never touches decrypted secrets — it sends the invocation envelope to the daemon and receives the sanitized response.

​
Auto-start

By default, aivault invoke auto-starts the daemon if it’s not already running. The daemon runs in the background and listens on a unix socket. Socket path:
  • Default: ~/.aivault/run/aivaultd.sock
  • If AIVAULT_DIR is set: $AIVAULT_DIR/run/aivaultd.sock
  • Override: $AIVAULTD_SOCKET

​
Shared daemon mode (cross-user invocation)

If you run untrusted agents under a separate OS user on the same machine, you can run a single daemon under your operator account and expose only its unix socket to the agent user. Start the daemon in shared mode:
In shared mode:
  • The daemon listens on a well-known shared socket path:
    • macOS: /Users/Shared/aivault/run/aivaultd.sock
    • Linux: /var/run/aivault/aivaultd.sock
  • Socket permissions are relaxed for group access (0660) and the socket directory is set to 0750.
  • The aivault CLI auto-discovers the shared socket, so the agent user can run aivault invoke ... with no extra flags or env vars.
  • When invoking via the shared socket, auto-start is suppressed (the agent account cannot and should not try to start its own daemon).

​
Configuration

When using a non-default AIVAULTD_SOCKET directory, aivault avoids changing permissions on arbitrary existing directories. You should ensure the socket directory permissions are appropriately restrictive for your environment.

​
Running the daemon manually

This starts the daemon in the foreground, useful for debugging. In normal operation, the CLI auto-starts it in the background.

​
When to disable the daemon

Set AIVAULTD_DISABLE=1 to run the broker in-process:
  • Development/debugging: easier to attach a debugger or see logs
  • Single-process deployments: when the extra isolation isn’t needed
  • Environments without unix sockets: (not common)
Next: Environment variables