ov agent

import { Aside } from ‘@astrojs/starlight/components’;

ov agent is a background daemon that holds your KEK in memory after a one-time authentication, then serves secret injection requests over a Unix socket. Use it on Linux servers and CI runners where prompting for a password on every ov run invocation is not practical.

How it works

ov agent start --machine-key /etc/ov/machine.kek
    ↓
daemon starts, loads KEK, listens on Unix socket
    ↓
ov run --agent --secrets DATABASE_URL -- ./migrate
    ↓
run sends signed request to socket → agent decrypts → subprocess runs

The agent authenticates requests via HMAC-SHA256 derived from the machine key. Only a client that holds the same machine key can send valid requests. The socket itself is protected by 0700 directory + 0600 permissions.

Plaintext secret values never cross the socket — the agent runs the subprocess itself and returns only the exit code.

Prerequisites

A machine key file is required to start the agent:

ov auth derive-machine-key --out /etc/ov/machine.kek
chmod 600 /etc/ov/machine.kek

See Machine key setup for details.

Commands

Command	Description
`ov agent start`	Start the agent daemon
`ov agent stop`	Stop the running agent
`ov agent status`	Show agent status
`ov agent install`	Install a systemd unit file

ov agent start

ov agent start --machine-key /etc/ov/machine.kek --app my-saas

Starts the daemon in the foreground. Use --foreground with systemd Type=simple.

Flag	Description
`--machine-key PATH`	Path to machine key file (required for HMAC socket auth)
`--app NAME`	Default app slug for `op=run` requests
`--socket PATH`	Unix socket path (default: `$XDG_RUNTIME_DIR/ov-agent/ov-agent.sock`)
`--pid-file PATH`	Path to write PID file
`--foreground`	Run in foreground (required for systemd `Type=simple`)

ov agent stop

ov agent stop
ov agent stop --pid-file /run/ov-agent/ov-agent.pid

Sends SIGTERM to the agent. Returns immediately — in-flight requests finish before the daemon exits.

ov agent status

ov agent status
ov agent status --machine-key /etc/ov/machine.kek

Queries the agent socket and prints uptime and version. If the socket is unreachable, falls back to checking the PID file.

Pass --machine-key if the agent was started with one — without it, the signed request will be rejected and status falls back to the PID file check.

ov agent install

ov agent install --machine-key /etc/ov/machine.kek
ov agent install --machine-key /etc/ov/machine.kek --enable

Writes a systemd unit file and prints the commands to enable and start it. Pass --enable to run systemctl daemon-reload && systemctl enable --now ov-agent automatically.

Flag	Description
`--machine-key PATH`	Path to machine key file (required)
`--socket PATH`	Unix socket path
`--unit-name NAME`	systemd unit name (default: `ov-agent`)
`--enable`	Run systemctl to enable and start immediately

systemd setup

The recommended production setup:

# 1. Create the machine key
ov auth derive-machine-key --out /etc/ov/machine.kek
chmod 600 /etc/ov/machine.kek

# 2. Install the systemd unit
ov agent install \
  --machine-key /etc/ov/machine.kek \
  --enable

The generated unit file uses Type=simple and restarts on failure. It runs as the current user.

Security model

Socket directory: 0700 (only the owning user can access it)
Socket file: 0600
HMAC-SHA256 per-request authentication when started with --machine-key
Replay window: ±30 seconds (timestamp-based; no stateful nonce store)
Plaintext values never cross the socket — the agent injects them directly into subprocess environments

Known limitations:

No server-side nonce store: a captured signed request can be replayed within the 30-second validity window
Interactive sessions (no --machine-key) have no socket authentication beyond filesystem permissions

Machine key setup — generating and managing machine keys
ov run — run commands with secrets injected (simpler, no daemon required)
CI/CD integration — using OpaqueVault in automated pipelines