tsafe-agent

Local unlock-session agent for tsafe.

Holds an unlocked vault session over a named pipe (Windows) or Unix socket (macOS / Linux) so subsequent tsafe commands skip the password prompt during the TTL window.

tsafe-agent is a local IPC surface, not a telemetry service. It holds one profile's unlock state in memory for the configured TTL and does not send product analytics, crash reports, update pings, secret names, or secret values to a vendor service.

In Agent Authority Firewall deployments, this agent is the local unlock-state companion used by safe command execution and bound MCP status checks. The bound MCP server still runs through a fixed authority contract and workdir; the agent does not turn the MCP server into a model-facing vault browser.

Install

Standalone Cargo install:

cargo install tsafe-agent

Some release channels bundle tsafe-agent beside the main tsafe binary. A plain cargo install tsafe-cli installs the compiled CLI only; it does not install this companion binary unless that channel says so explicitly. The meta-crate path cargo install tsafe builds the bundled suite.

Usage

Start the agent and unlock the vault:

eval $(tsafe agent unlock --ttl 8h)

eval is required because the agent prints the socket address and session token as a shell assignment. The token is never written to shell history this way.

Once the agent is running, subsequent commands in the same shell session skip the password prompt:

tsafe get MY_SECRET

tsafe exec -- my-app

To unlock with a specific profile:

eval $(tsafe agent unlock --profile work --ttl 4h)

TTL

Two TTL values control agent lifetime:

• Idle TTL — the agent exits if no request arrives within this window.
• Absolute TTL — a hard deadline regardless of activity. Set via --ttl; defaults to 8 hours.

A background watchdog thread enforces the absolute deadline and wakes the accept loop when it fires so the agent exits promptly.

Status

tsafe agent status --json

Returns machine-readable agent state including the socket path, profile, and time remaining.

Password acquisition

The agent acquires the vault password using this priority chain:

1. OS keychain — macOS Keychain or Linux Secret Service, using the same entry as tsafe biometric enable. Single call, no double-prompt.
2. TSAFE_VAULT_PASSWORD env var — accepted but warned loudly because the value is visible in /proc/self/environ and docker inspect. Prefer the keychain.
3. Interactive TTY prompt — via rpassword, the original behaviour.

Security model

• PID verification — on each OpenVault request, the agent checks that the requesting_pid field in the JSON matches the actual PID of the connecting process (via SO_PEERCRED on Linux, getpeereid + LOCAL_PEERPID on macOS, GetNamedPipeClientProcessId on Windows). A PID mismatch is rejected.
• Socket permissions — the Unix socket file is created with mode 0600 (owner-only). On Windows, only one named-pipe instance is created per session.
• Zeroize on drop — the vault password is held in a Password(String) newtype that implements ZeroizeOnDrop; the memory is overwritten before deallocation.
• Signal handling (Unix) — SIGTERM and SIGINT set the stop flag so the accept loop drains cleanly and the SocketCleanup RAII guard unlinks the socket file. SIGHUP is ignored so terminal hangup does not kill the agent mid-session.

CellOS broker (Unix only)

On macOS and Linux the agent also binds a second Unix socket for the CellOS subsystem. CellOS callers authenticate by UID match (SO_PEERCRED / getpeereid) and a per-cell token. Supported requests:

• Resolve — look up a secret by key and cell ID; registers the cell on first call and validates the token on subsequent calls.
• RevokeForCell — mark a cell ID as revoked; subsequent Resolve calls for that cell are rejected.

Both operations are appended to the profile audit log.

License

Same as the tsafe workspace — see the repository root.