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.

If you have ever shipped an AI product, you know the pattern: half the codebase is plumbing — users, API keys, embeddings, conversation history, tool calling, traces. SOAT solves all of it once, exposes it through four equivalent client surfaces, and gets out of your way.

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 soat-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

Operations

• Encrypted secrets for provider keys
• HMAC-signed webhooks with event-pattern subscriptions
• Trace records for every generation — tool calls, latency, and cost-relevant fields

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

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

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
• Modules — deep-dives into every resource type