Installation
Connection and configuration
GATEWAY_BASE_URL / GATEWAY_API_KEY / GATEWAY_MODEL together (there is no fallback to OPENAI_*). AGENT_HARNESS=dsh is the default; use AGENT_HARNESS=native for the in-process loop. DSH_BIN / DSH_HOME_ROOT / DSH_POOL_MAX / DSH_IDLE_TTL_SEC tune the child-process pool.
Governed execution consists of four fail-closed seams: egress policy (AGENT_EGRESS_MODE), audit (AGENT_AUDIT_DIR), metering (AGENT_METERING_DB_PATH) and credentials (AGENT_CREDENTIAL_PROVIDER). The default AGENT_EGRESS_ENFORCEMENT=proxy needs no sidecar; network requires EGRESS_PROXY_IMAGE and CONTROL_PLANE_URL and fails closed at boot when either is missing.
Concepts
Requests carry
Authorization: Bearer <key> and OpenAI-Beta: agents=v1.
Language bindings
All five SDKs share the same shape:Agent → Session → run / runStreamed, with finalOutput or final_output on the result. memory.backend accepts cloud, local (aria memo CLI) or both; a per-call override wins.
Tool families and governance
Built-in tools are grouped into families:fs, shell, jobs, terminal, skills, web, ask, plan, todo and memo. The browser sandbox offers a six-image catalog (chromium, firefox, webkit, chrome, edge, brave). Every call passes through permission presets and approvals; approval frames arrive as agent.turn.approval.*.
Read-only governance endpoints: GET /v1/governance/status (enforcement, metering, compression, credentials), GET /v1/governance/usage (records, tokens, compression), and GET /v1/governance/audit (optional kind / limit / cursor; full NDJSON export requires read_raw). Policy, credential and checkpoint writes require admin.
When to use aria-agent, aria-router or aria-engine
- Agent scaffolding (tool calls and planning):
aria-agent - Typed System One decisions only: aria-engine
- OpenAI-compatible reasoning gateway (chat + policy): aria-router