SOIT

Governed Agent Runtime for Enterprise AI Systems.

Build  ·  Govern  ·  Execute  ·  Observe

Quick start  ·  Architecture  ·  Documentation  ·  Roadmap  ·  Changelog  ·  Contributing  ·  中文

What is SOIT?

SOIT Community is the open-source Agent Runtime and Governance Platform for teams that need AI agents to touch real enterprise systems without losing control. It combines agent building, workflow execution, knowledge retrieval, tool/MCP access, model routing, and runtime observability with the governance layer enterprises need before agents can operate on sensitive data and systems.

The core product wedge is governed execution: every agent run is scoped by permissions, bound to approved capabilities, protected by secret boundaries, constrained by egress policy, traced through a runtime ledger, attributed with cost, recorded in audit logs, and inspectable through replay.

Already calling models from your own code? SOIT also serves an OpenAI-compatible API under /v1. Point an OpenAI SDK, LangChain or the OpenAI Agents SDK at it with a SOIT API key and every call becomes a governed run: per-key rate limits, quotas, address and model allowlists, budgets that stop spend, content-free runs, audit, cost attribution, and failover across providers through virtual models, with no change to application code. See the gateway guide and examples. The same keys call the workspace's governed tools directly (/api/v1/tools) or from any MCP client such as Claude Code or Cursor (/mcp, see SOIT as an MCP server), and the soit command line runs agents, replays regression sets on a new model and exports evidence.

SOIT is not trying to be another lightweight chatbot builder. It is built for teams that already proved agents can be useful and now need permissions, secrets, outbound-network control, auditability, cost accountability, traceability, and replay before those agents can be trusted in production workflows.

Why SOIT?

	Notebook frameworks	Hosted agent products	Cloud-vendor agents	SOIT
Multi-tenant isolation	—	partial	yes	first-class
Model-neutral routing	yes	partial	vendor-locked	first-class
Workflow + Agent dual model	partial	one or the other	partial	both, equal
Audit-ready execution ledger	—	partial	partial	built-in
Permission + secret boundaries	manual	partial	cloud-native	built-in
Egress control	manual	partial	cloud-native	policy-driven
Cost, trace, and replay evidence	manual	partial	partial	runtime-native
Self-hosted, single command	yes	—	—	yes
Spec-first contracts	—	—	—	every primitive

SOIT is the platform we wished we had when our agents graduated from notebooks to production.

The four pillars

SOIT is organized around four capabilities. Each is a first-class citizen, designed to be used independently or composed together.

Build — Assemble agents from typed capabilities

Compose agents from a unified capability registry: models, knowledge bases, workflows, skills, and tools. Every binding is typed, versioned, and source-agnostic — a tool from a plugin, an MCP server, or a built-in adapter looks identical from the agent's perspective.

• Visual agent assembly console with versioning and release management, including a review state on drafts so work in progress is distinguishable from work waiting on somebody
• DAG workflow editor with 8 core node types — input, LLM, knowledge retrieval, tool, condition, transform, variable assignment, and output — plus plugin-exported node types resolved through the plugin registry
• Knowledge ingestion pipeline for PDF, DOCX, Markdown, and HTML, with chunking, embedding, and Milvus-backed retrieval, plus sources that keep a knowledge base in step with an S3-compatible bucket or a website on a schedule (connectors guide)
• MCP-friendly: any Model Context Protocol server resolves into the runtime tool registry without code changes. Transport is streamable HTTP. Protected servers are reached with OAuth 2.1 using authorization-server discovery (RFC 9728, RFC 8414 / OpenID Connect) and resource-bound tokens (RFC 8707), via the client_credentials grant — SOIT calls MCP servers on its own behalf, so the browser-based authorization-code flow is not implemented. The adapter that calls MCP servers targets the MCP SDK v1 line and does not yet speak the stateless 2026-07-28 revision; SOIT's own MCP endpoint serves it (see SOIT as an MCP server)
• Plugin-first governance: MCP servers and Skills are installed as Plugin artifacts, so permission checks, secret injection, egress limits, audit, cost attribution, trace, and replay apply automatically at runtime

Execute — Run with reliability and reproducibility

Every execution — chat turn, agent loop, or workflow run — flows through the same runtime ledger. Outbox-pattern event dispatch durably records state transitions and provides at-least-once delivery; consumers remain responsible for idempotent side effects.

• Unified Run / Task / RunStep / Trace ledger across all execution types
• Outbox-based event-driven runtime with checkpoints and idempotency
• Multi-model routing across OpenAI, Anthropic, DeepSeek, Qwen, Ollama, and any OpenAI-compatible endpoint
• Virtual models: one vmodel: name for an ordered list of models, tried in turn when a provider is down, rate-limited or missing a capability
• An OpenAI-compatible gateway under /v1 (chat completions, embeddings, images, model listing) that runs every call through the same ledger
• Cost-aware execution with per-step token and latency accounting
• Graceful failure handling with retries, fallback chains, and human-in-the-loop approvals: a run that stops for a decision records the request, so it can be answered from the task rather than only by whoever was watching the stream
• Cron schedules that hand work to the same durable path the API uses, so a scheduled run is an ordinary run; a missed occurrence is skipped unless the schedule asks to catch up

Observe — Workspace-level visibility, not just request logs

Most platforms give you a list of runs. SOIT gives you a workspace control console built directly on the runtime ledger.

• Live workspace summary: active agents, run volume, cost burn, failure rate
• Drill-down by agent, by workflow, by tool, and by source (source_kind=plugin | mcp | builtin)
• Trace timeline with full step replay
• Knowledge retrieval quality metrics
• Regression trend across the last runs of the release gate: pass rate, what regressed against the baseline, and whether the gate blocked
• OpenTelemetry-compatible tracing, structured JSON logs, and Prometheus metrics

Govern — Permissions, secrets, egress, audit, cost, trace, replay

Enterprise platforms live and die by what they refuse to do. SOIT treats governance as a kernel concern, not an afterthought.

• Tenant and workspace scoping enforced at every API and data layer
• RBAC with resource-level permissions and grant inheritance
• Vault-backed secret management with workspace-scoped visibility
• Egress policy enforcement for outbound HTTP calls and tool adapters, with example policies for the common scenarios
• Per-version capability allowlists for models, knowledge, workflows, tools, plugins, and MCP servers
• Full audit log of privileged operations and runtime tool use, searchable by actor, object, outcome and time window
• Versioned governance policy: every save of a workspace's egress rules and usage limits appends a revision, an earlier one can be restored, and the policy in force carries a content-derived identifier that refused requests are recorded against
• Cost attribution by run, model, tool, workflow, and workspace, with daily usage aggregates per entry, key, principal, provider and model
• Budgets for a workspace, key, member or agent that refuse calls at a hard limit and alert owners, admins and team channels at thresholds
• Per-key limits (rate, daily calls and tokens, allowed addresses and models) and service principals, so pipelines do not borrow a person's key
• Content-free runs: a workspace or key can keep prompts, outputs, tool arguments and results out of its run records (runs, steps, audit, tool calls, traces) while tokens, costs and outcomes are still recorded; conversations keep their messages so they can continue (what is kept)
• Trace timeline and replay for agent, workflow, response, and tool-call execution
• Separation of duties: changing egress policy, secrets, or installed plugins requires workspace Owner/Admin, not the Dev role that builds and runs agents
• Scoped, expiring API keys: a key carries an explicit read/write/admin ceiling and never inherits its owner's full role

Content safety is a built-in baseline plus a pluggable service. SOIT ships a deterministic in-process provider that inspects content entering and leaving the runtime for credentials (private keys, cloud and provider tokens, JWTs) and for the identifiers that are personal data everywhere (email, phone, card numbers validated by checksum, national ids). Credentials are redacted by default; personal data is recorded rather than rewritten, because rewriting real work silently is worse than reporting it. Findings go into run evidence, never the matched text. It is pattern matching, not a classifier: it cannot judge tone, intent, jailbreaks or confidentiality. A deployment that needs those sets CONTENT_SAFETY_PROVIDER=http and points at a classifier it operates, through the same port.

Quick start

The fastest way to try SOIT locally is the lite profile: five containers (PostgreSQL with pgvector, Redis, the API, the web UI and one background worker), no .env required.

git clone https://github.com/soit-ai/soit.git
cd soit
docker compose -f docker/docker-compose.lite.yml up -d

Then open http://localhost:5000 and sign in as admin@example.com / changeme123 (override with BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD).

What you get on first launch:

• Web UI on :5000, API on :9200
• Every feature: vectors in PostgreSQL through pgvector, files on a local volume, secret values sealed in the database with a key derived from SECRET_KEY
• Database migrations applied automatically
• An empty Community workspace where Agents, Workflows, and Knowledge bases can be created through the UI without demo seed data

The lite profile is for evaluation; the settings refuse pgvector and sealed secrets when ENVIRONMENT=production. The full topology runs Milvus, MinIO and Vault the way a production deployment does:

cp .env.example .env
docker compose --env-file .env -f docker/docker-compose.yml up -d postgres redis minio etcd milvus vault migrate bootstrap api web knowledge-ingest-worker outbox-dispatcher scheduler

Deploy from released images

Instead of building locally, run the same topology from the signed release images on GHCR (see Releases for digests and attestations):

docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.images.yml pull
docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.images.yml up -d --no-build postgres redis minio etcd milvus vault migrate bootstrap api web knowledge-ingest-worker outbox-dispatcher

Pin a version with SOIT_IMAGE_TAG (defaults to v1.8.0). Images can be verified with gh attestation verify. The released web image serves the API at the default http://localhost:9200/api/v1; if you override the API host port, build the web image from source with VITE_BASE_URL instead.

Not every demo needs all of these services. docs/minimal-topology.md lists what each container is for, which ones a scenario can leave out, and what stops working when it does.

For a local development setup with hot reload (Python and Node), see docs/development.md.

For the Phase 1 bilingual quickstart, demo seed, and smoke evidence path, see docs/quickstart.md.

Deterministic Community Demo Fixture

From the repository root, start the full local demo stack:

docker compose --env-file .env -f docker/docker-compose.yml up -d postgres redis minio etcd milvus vault migrate bootstrap api web knowledge-ingest-worker outbox-dispatcher

Then open http://localhost:5000 and sign in with BOOTSTRAP_ADMIN_EMAIL / BOOTSTRAP_ADMIN_PASSWORD from .env (defaults: admin@example.com / changeme123). The API is available at http://localhost:9200/api/v1.

If a local service already owns one of the default host ports, override only the host binding through the *_PUBLISHED_PORT variables in .env, for example MINIO_API_PUBLISHED_PORT=19000 API_PUBLISHED_PORT=19200 WEB_PUBLISHED_PORT=15000. All ten variables, their defaults and what each port exposes are listed in docs/quickstart.md.

For the backend smoke path:

cd server
uv run python scripts/bootstrap_enterprise_mvp.py
uv run pytest tests/integration/test_enterprise_agent_mvp.py -q

The historical script names contain enterprise_mvp, but these fixtures run entirely on SOIT Community and do not import or require the private Enterprise package.

Current Community Demo Focus

The current non-Docker demo gate focuses on one repeatable governed support loop:

• Refund-policy knowledge answer with citation evidence.
• Support-ticket workflow execution through a governed tool call.
• Parent Agent run linked to child Workflow run.
• Observe run detail showing response events, run steps, tool calls, child workflow runs, costs, citations, and audits.

This path is intentionally narrow. It is the quality baseline for expanding SOIT without turning the platform into a collection of disconnected demos.

Architecture

SOIT follows a strict hexagonal architecture: a stable kernel at the center, replaceable adapters at the edges, and domain modules in between.

┌─────────────────────────────────────────────────────────────┐
│  API Layer:  REST, WebSocket, SSE                           │
├─────────────────────────────────────────────────────────────┤
│  Kernel  (stable core)                                      │
│    Runtime, Identity, Trace, Specs, Security                │
│    Events, Responses, Observe, Registry                     │
│    Ports:  LLM, Tools, Vector, Storage, Secrets             │
├─────────────────────────────────────────────────────────────┤
│  Domain Modules                                             │
│    Agent, Workflow, Knowledge, Plugin, Evaluation           │
├─────────────────────────────────────────────────────────────┤
│  Adapters                                                   │
│    OpenAI, Anthropic, LiteLLM, Milvus, pgvector, Vault      │
├─────────────────────────────────────────────────────────────┤
│  Infrastructure                                             │
│    PostgreSQL, Redis, Milvus or pgvector, S3 or files       │
└─────────────────────────────────────────────────────────────┘

Five principles govern every design decision in SOIT:

1. Spec-First. Every primitive — Agent, Workflow, Tool, Knowledge, Plugin — has a versioned JSON Schema that contracts both API and storage layers.
2. Scope-By-Default. Every resource carries a tenant_id and workspace_id. No exceptions, no escape hatches.
3. Trace Everything. Every execution creates a Run with structured RunSteps. There are no silent operations.
4. Gateway-Only. External calls go through governed gateways. Business code never opens a raw HTTP client or LLM SDK.
5. Immutable Versions. Versions are append-only. Releases move pointers, never mutate history.

For the full architecture deep-dive, see server/docs/architecture/README.md.

Use cases

SOIT is designed for teams who need agents to do real work in production:

• Internal copilots — RAG-powered assistants over private documentation, with permission inheritance from your existing IAM
• Workflow automation — Long-running, retry-safe agent workflows with human approval steps and full audit trails
• Customer-facing AI features — Multi-tenant agent serving with per-customer isolation, quotas, and cost attribution
• Compliance-sensitive AI — Agents in regulated environments where every model call must be explainable and every secret must be vaulted
• Multi-model strategies — Cost-optimized routing across providers, with graceful fallback and per-model performance tracking

Tech stack

Layer	Choices
Backend	Python 3.12 · FastAPI · SQLModel · Alembic · OpenTelemetry
Frontend	TypeScript · React 19 · React Router 8 · TailwindCSS 4 · Zustand · React Query · React Flow
Data	PostgreSQL 15 · Redis 7 · Milvus 2.5 or pgvector · S3-compatible storage (MinIO) or local files
Security	HashiCorp Vault (sealed database store for evaluation installs) · JWT · bcrypt
LLM	OpenAI · Anthropic · DeepSeek · any OpenAI-compatible endpoint · LiteLLM for other providers

Roadmap

We ship in tight, themed iterations. The current focus areas:

• Outbox-based event-driven runtime (Wave A and B)
• Capability registry with source-agnostic tool binding
• Agent versioning and release management
• Hexagonal kernel with strict port-adapter boundaries
• Workspace observe console
• Agent evaluation with regression sets, LLM judging and a release gate
• Approval workflows with human-in-the-loop checkpoints
• Five-container lite profile for evaluation
• OpenAI-compatible gateway: any OpenAI SDK through SOIT's budgets, audit and ledger
• SOIT as an MCP server for agents that run elsewhere
• Standalone gateway processes (SOIT_ROLE=gateway) and model servers on private networks
• Signed Enterprise licenses and extension packages
• Anthropic Messages API on the gateway, for Claude Code and the Anthropic SDKs
• Evaluation datasets with revisions, and knowledge bases synced from S3 buckets and websites
• Cost reconciliation against provider bills, and document-level knowledge permissions
• Approval assignment, deadlines, delegation and server-side workflow resume
• Cost-aware multi-model routing policies
• Agent specifications as YAML files, exported and imported

See the full roadmap and contributing guide to track direction and propose changes.

Operational and release references:

• Community release process
• Backup and restore runbook
• Security policy

Contributing

We welcome contributions of all sizes. Before opening a PR:

1. Read CONTRIBUTING.md for setup and code style
2. Review the roadmap and keep proposed changes scoped
3. For larger changes, include the problem statement and verification plan in the PR description

SOIT follows a spec-first development model: significant features should start from a written design note or public documentation update before code changes. This catches design problems early and keeps the architecture coherent as the project grows.

Questions and contributions

Use the contributing guide for local setup, quality checks, and pull request expectations. Public community channels should be listed here only after their URLs are live and maintained.

License

SOIT Community is released under the Apache License 2.0.

The core platform is and will remain open source. Some advanced enterprise features — SSO, advanced audit reports, SLA monitoring, multi-region deployment — are available in SOIT Enterprise and SOIT Cloud, separate commercial offerings built on the same runtime. For commercial inquiries, contact info@soit.ai.

---

_{Built with care for teams who run AI in production.}