Introduction

SOAT is the infrastructure layer for production-ready AI agents. It bundles IAM, file and document storage, vector search, conversational memory, agent orchestration, multi-agent workflows, retrieval-augmented generation, declarative stack deployment, and a full MCP server into a single self-hostable Node.js service backed by PostgreSQL.

The platform is organized around the four layers of an agent system: the harness (what an agent can reach), the loop (what proves a run did the job), the graph (what happens next), and the ratchet (what proves a change was an improvement). The first three are shipped in depth; the ratchet is the active build front — see Where SOAT is going.

What you get out of the box

Identity & access management

• Users, projects, and project memberships
• Per-resource permissions via reusable IAM policy documents
• User JWTs, project API keys, and personal API keys with policy attachments

Storage & retrieval

• Files and structured documents scoped to projects
• pgvector embeddings and semantic search with score thresholds
• Memories as durable context stores, plus Knowledge for unified search across documents and memory entries

Agents & conversations

• Configurable agents with HTTP, MCP, client-side, and builtin-platform tools
• Multi-step reasoning loops with tool_choice, step rules, and boundary policies
• Multi-agent workflows: agents call other agents as tools
• Async generations: long-running jobs you can poll or wait on
• Sessions — a 1↔1 user/agent interface that hides actors and conversations
• Conversations — multi-party message engine when you need full control
• Chats — raw LLM completions when you don't need an agent at all

Orchestration & automation

• Orchestrations — deterministic DAG pipelines with parallel rounds, conditions, retries, and durable resumption
• Workflows — state graphs that durable tasks live in and move through, including backward
• Triggers start a flow on a cron schedule, an inbound webhook, or on demand

Governance & safety

• Guardrails classify every tool call from its actual arguments — deterministically, before anything executes
• Approvals — a human-decision queue with frozen evidence, hard expiry, and a recurrence view over repeated corrections
• Quotas fail closed on request, token, or cost caps; Usage meters every call with alert thresholds
• Append-only agent versions with staged canary rollout and served-version stamping

Operations

• Encrypted secrets for provider keys
• HMAC-signed webhooks with event-pattern subscriptions
• Traces for every generation — tool calls, latency, and cost-relevant fields — plus exceptions, activity, and an audit log

Declarative deployment

• Agent formations to define full agent stacks (providers, memories, tools, agents) in JSON/YAML
• Dependency-aware provisioning with operation history and event logs for each deployment

Where SOAT is going

Everything above records what agents did or constrains what they may do. The direction of the platform is the layer that governs what they become: the ratchet — produce a verdict from evidence, gate every change on the verdict, keep history append-only so nothing regresses silently.

The ratchet is now closed end to end: versioned agents, canary rollout, the approvals recurrence view, and —

• Evaluations — datasets, scorers, and scored runs of the real agent, comparable against a baseline, answering "did this change make the agent worse?" with a pass/fail verdict
• Eval-gated promotion — a canary release that promotes only on a passing eval run against that canary, not on a judgment call

Promotion stays human-gated by design: the platform owns the queue, the recurrence signal, and the verdict — a human owns the judgment. The full framing is in The Layers of an Agent System, and sequencing lives in the roadmap.

Architecture

SOAT runs as a single Node.js server backed by PostgreSQL with pgvector. One process exposes both the REST API and the Streamable HTTP MCP endpoint — both call the same business-logic layer and the same permission engine.

One backend, four surfaces

Every operation in SOAT is reachable through four interchangeable client surfaces. They share the same permission check, the same business logic, and the same response shape — pick the one that fits the job.

Surface	Best for	Docs
REST API	Backend services, custom integrations	API Reference
MCP server	Claude Desktop, Cursor, and other MCP-aware runtimes	MCP
CLI (soat)	Scripts, CI pipelines, and local exploration	CLI
SDK (@soat/sdk)	TypeScript and JavaScript applications	SDK

See Choosing a Client Surface for the trade-offs. Each operation is gated by a single permission action (e.g. documents:CreateDocument) that is enforced consistently across all four surfaces. See IAM & Policies for how policies are evaluated.

Example — create a document

CLI

soat create-document \
  --project-id proj_ABC \
  --title "Release Notes" \
  --content "Initial release."

SDK

import { SoatClient } from '@soat/sdk';

const soat = new SoatClient({
  baseUrl: 'https://api.example.com',
  token: 'sk_...',
});

const { data, error } = await soat.documents.createDocument({
  body: {
    project_id: 'proj_ABC',
    title: 'Release Notes',
    content: 'Initial release.',
  },
});

curl

curl -X POST https://api.example.com/api/v1/documents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"proj_ABC","title":"Release Notes","content":"Initial release."}'

Where to next

• Get started — bring up SOAT with Docker Compose in five minutes
• Key concepts — the mental model behind projects, agents, and sessions
• Choosing a client surface — REST, SDK, CLI, or MCP
• Platform modules — deep-dives into every resource type