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

CLI process                           Daemon process (aivaultd)
  │                                     │
  │  invoke openai/chat-completions     │
  │  ─────────────────────────────────▶ │
  │  (unix socket)                      │
  │                                     ├─ Decrypt secret from vault
  │                                     ├─ Validate capability policy
  │                                     ├─ Inject auth into request
  │                                     ├─ Proxy to upstream provider
  │                                     ├─ Sanitize response
  │  ◀───────────────────────────────── │
  │  response                           │
  ▼                                     ▼
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: 
aivaultd --shared
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

VariableDefaultDescription
AIVAULTD_DISABLE0Set to 1 to skip the daemon and run the broker in-process
AIVAULTD_AUTOSTART1Set to 0 to require the daemon already running (no auto-start)
AIVAULTD_AUTOSTART_ONCE0Set to 1 to auto-start the daemon in --once mode (serve one request then exit). Enabled automatically when AIVAULT_DIR is set.
AIVAULTD_SOCKET~/.aivault/run/aivaultd.sockOverride the unix socket path
AIVAULTD_SOCKET_MODE0600Override the unix socket file mode (octal). Useful for allowing group access (e.g. 0660).
AIVAULTD_SOCKET_DIR_MODE0700Override the unix socket directory mode (octal). Useful for allowing group traversal (e.g. 0750).
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

# Use the default socket path
aivaultd

# Or specify a socket explicitly
aivaultd --socket ~/.aivault/run/aivaultd.sock

# Use the shared socket path + group-friendly permissions
aivaultd --shared

# Serve a single request and exit (useful for tests)
aivaultd --once
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)
AIVAULTD_DISABLE=1 aivault invoke openai/chat-completions --body '...'
Next: Environment variables