Skip to Content
AgentOverview

Agent

onprest-agent runs inside the on-prem network, next to the databases, folders, and APIs its capabilities use. It reads capability.yaml, connects out to the gateway over WebSocket, and runs capabilities when the gateway forwards a call. It opens no listening port.

Runtime model

  • One binary, configured by one capability.yaml. Pass it with --config; without it, the agent uses AGENT_CAPABILITY_FILE or capability.yaml next to the binary.
  • The configuration is loaded once at startup. Restart the agent to apply changes.
  • If the gateway is unreachable, the agent retries every 30 seconds.
  • Up to runtime.max_concurrent_requests calls (default 16) run at once, with a waiting queue of the same size. Responses may complete in a different order than requests arrived.
  • Detailed errors go to local log files next to the binary, never to the gateway.

Startup checks

Before it connects, the agent:

  1. Loads and checks capability.yaml.
  2. Prepares every source a capability references: reads secret and certificate files, checks folder roots, and, for databases, connects and runs EXPLAIN for each SQL statement. HTTP sources are not called.
  3. Checks every Wasm module without running it.
  4. Opens its private spool directory and finishes any cleanup left from a previous run.

If any step fails, the agent exits without connecting, the gateway keeps reporting agent_connected: false, and the reason is on stderr or in the local log. A configuration with no DB capabilities needs no database.

Checking without starting

Two commands run the same checks without taking over from a running agent:

  • onprest-agent validate --config PATH runs steps 1 to 3 and exits. Use it before every restart.
  • onprest-agent doctor --config PATH additionally checks DNS, TLS, and key authentication against the gateway, without opening the normal connection.

Neither runs a capability. See the CLI reference for their output and Troubleshooting for what to do when they fail.

Configuration

The agent’s own settings (runtime limits, spool and identity directories, gateway connection, logging) are in Agent configuration. Capabilities and their sources are described under Capabilities.

LogsConfiguration