Symbiont Documentation¶

Policy-governed platform for building agentic applications. Execute AI agents and tools under explicit policy, identity, and audit controls.

Start where your job starts¶

These docs serve three different jobs. They need different pages in a different order, so pick the path rather than reading the list.

Evaluating whether this is trustworthy. You need to know what is actually enforced, what is merely recorded, and where the boundaries of the claim are. You may never write a .symbi file.

1. Prove the gate in 30 seconds — below; offline, no install commitment
2. Security Model — trust boundaries, the three isolation tiers, what is trusted rather than verified
3. Prepared Calls — what an authorization is, and why it cannot be replayed
4. Protected Run Audit — what the journal proves, and what it does not
5. Approval Lifecycle — review-bound release, deadlines, and the limits of approver identity
6. Containment Guide — current coverage and the gaps stated plainly
7. The published evaluation — DOI 10.5281/zenodo.20043247

Building and operating agents. You need a running project, then a fence around it that holds when someone else is on call.

1. Prove the gate — start with a refusal, not a success
2. Getting Started — install, symbi init, first agent
3. DSL Guide — agent definitions, plus Inline Effect Policies for the enforced rule subset
4. Command Isolation — configure the worker your tools actually run in
5. ToolClad — declarative tool contracts and scope enforcement
6. Approval Lifecycle — the correct answer to a denial that should involve a person
7. Runtime Architecture and API Reference — when you deploy it
8. Symbi Shell (Beta) — interactive authoring and the Gate panel

Reading the specification. You care about conformance, reproducibility, and whether the standard is separable from the vendor.

1. Open Agent Trust Stack — the specification (CC BY 4.0), OATS Extended C1–C7 + E1–E8
2. Reasoning Loop — the typestate ORGA cycle as implemented
3. Prepared Calls — the authorization object and its regression coverage
4. Security Model — tier guarantees, including Tier 3 guest attestation
5. Published work — Typestate ORGA Loops, ToolClad, Empirical Evaluation
6. Contributing — the reproduction harnesses live in the repository

Setting up with an AI coding agent? Point it at https://symbiont.dev/agent-guide.md before it touches anything. It is a stable plain-text instruction file with current grammar and flags, and a standing rule never to resolve a setup error by broadening policy.

Prove it first — offline, no API key¶

Start by making Symbiont refuse something. This is the same Cedar gate the runtime wires into the live reasoning loop, evaluated standalone, so a denial here is a denial there. It needs no model provider, no Docker, and no project.

Install:

curl -fsSL https://symbiont.dev/install.sh | bash

Write two policies and evaluate against them:

mkdir -p /tmp/p && cat > /tmp/p/policy.cedar <<'EOF'
forbid(principal, action == Symbi::Action::"tool_call::list_agents",   resource);
permit(principal, action == Symbi::Action::"tool_call::system_health", resource);
EOF

echo '{"tool_name":"list_agents"}'   | symbi policy evaluate --stdin --policies /tmp/p --json
echo '{"tool_name":"system_health"}' | symbi policy evaluate --stdin --policies /tmp/p --json

{"decision":"deny","reason":"deny policies matched: policy_0","tool":"list_agents", ...}
{"decision":"allow","reason":"allow policies matched: policy_1","tool":"system_health", ...}

Then watch argument validation stop a call before it executes:

symbi tools init greet
symbi tools validate
symbi tools test greet --arg target=example

greet                                    OK

  ✓ target (string): example → OK

  Command:   greet example
  Cedar:     Tool::Greet / execute_tool

  [dry run — command not executed]

The denial is the demonstration. A quick start that ends in a successful run proves only that a program ran — which every agent framework's quick start also proves.

Running an agent needs a model provider; continue in Getting Started.

What is Symbiont?¶

Symbiont is a Rust-native platform for executing AI agents and tools under explicit policy, identity, and audit controls.

Most agent frameworks focus on orchestration. Symbiont focuses on what happens when agents run in real environments with real risk: untrusted tools, sensitive data, approval boundaries, audit requirements, and repeatable enforcement.

How it works¶

Symbiont separates agent intent from execution authority:

1. Agents propose actions through the reasoning loop (Observe-Reason-Gate-Act)
2. The runtime prepares each action — normalizing arguments and freezing the contract, resolved effect, selected sandbox and deadline into one immutable call
3. Policy decides — Cedar and the supported inline rules must both permit; denied actions are blocked, and actions marked for approval are routed to a human
4. The record lands first — the required pre-effect journal write must succeed before dispatch
5. The worker executes — inside the selected sandbox, never on the host

Model output is never treated as execution authority. The runtime controls what actually happens.

Core capabilities¶

Additional capabilities: threat scanning for tool/skill content, cron scheduling, persistent agent memory, hybrid RAG search (LanceDB/Qdrant), webhook verification, delivery routing, OTLP telemetry, HTTP security hardening, channel adapters (Slack/Teams/Mattermost), and governance plugins for Claude Code and Gemini CLI.

Scaffold a project¶

symbi init        # Interactive: profile, SchemaPin mode, sandbox tier.
                  # Writes symbiont.toml, agents/, policies/, docker-compose.yml,
                  # and a .env with a generated SYMBIONT_MASTER_KEY.
symbi run <agent> # Run a single agent without starting the full runtime
symbi up          # Start the full runtime with auto-configuration
symbi shell       # Interactive agent orchestration shell (Beta)

Non-interactive, for CI:

symbi init --profile assistant --schemapin tofu --sandbox tier1 --no-interact

With Docker — pass --dir, because the image WORKDIR is not your mount:

docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace
docker compose up

Runtime API on http://localhost:8080, HTTP Input on http://localhost:8081.

Other installation routes — Homebrew (brew tap thirdkeyai/tap && brew install symbi), cargo install symbi (needs Rust 1.89+ and protobuf-compiler), or GitHub Releases. Full detail in Getting Started.

Your first agent¶

metadata {
    version = "1.0.0"
    author = "your-name"
    description = "Writes one reviewed file"
}

agent writer() {
    capabilities = ["write"]

    with sandbox = "docker", timeout = 20.seconds {}

    policy files {
        allow: "edit_file" if invocation.arguments.path == "result.txt"
        deny:  "edit_file" if invocation.arguments.content == ""
    }
}

Inline policy blocks are compiled and enforced alongside Cedar — both must permit. The supported subset is deliberately small, and a rule the runtime cannot enforce fails the invocation before the model is called rather than being silently ignored. See Inline Effect Policies for the exact grammar, and the DSL Guide for metadata, schedule, webhook, and channel blocks.

Interactive shell (Beta)¶

symbi shell is a ratatui-based terminal UI for authoring agents, tools, and policies with LLM assistance, orchestrating multi-agent patterns (/chain, /parallel, /race, /debate), managing schedules and channels, and attaching to remote runtimes. Press Ctrl+G to open the Gate panel and review held actions. Status is beta — the command surface and persistence formats may still shift between minor releases. See the Symbi Shell guide and shell workspace configuration.

Deploying single agents (Beta)¶

The shell's /deploy command packages the active agent and ships it to Docker (/deploy local), Google Cloud Run (/deploy cloudrun), or AWS App Runner (/deploy aws). The OSS stack is single-agent; multi-agent topologies compose via cross-instance messaging. See Symbi Shell — Deployment.

Architecture¶

graph TB
    A[Policy Engine — Cedar] --> B[Core Runtime]
    B --> C[Reasoning Loop — ORGA]
    B --> D[DSL Parser]
    C --> P[Prepared Call]
    P --> G[Escalation Gate]
    P --> E[Sandbox Worker]
    P --> I[Protected Journal]

    subgraph "Scheduling"
        S[Cron Scheduler]
        H[Session Isolation]
        R[Delivery Router]
    end

    subgraph "Channels"
        SL[Slack]
        TM[Teams]
        MM[Mattermost]
    end

    subgraph "Knowledge"
        J[Context Manager]
        K[Vector Search]
        L[RAG Engine]
        MD[Agent Memory]
    end

    subgraph "Trust Stack"
        M[MCP Client]
        N[SchemaPin]
        O[AgentPin]
        SK[Threat Scanner]
    end

    C --> S
    S --> H
    S --> R
    R --> SL
    R --> TM
    R --> MM
    C --> J
    C --> M
    J --> K
    J --> L
    J --> MD
    M --> N
    C --> O
    C --> SK

Security model¶

Symbiont is designed around a simple principle: model output should never be trusted as execution authority.

Actions flow through runtime controls:

• Zero trust — all agent inputs are untrusted by default
• Prepared calls — the authorized invocation is frozen, single-use, and re-checked at dispatch
• Policy checks — Cedar plus the supported inline rules, both fail-closed, before every tool call
• Tool verification — SchemaPin cryptographic verification of tool schemas
• Containment — Docker, gVisor or Firecracker workers, with no host fallback
• Operator approval — human review of the complete request, released by digest rather than by ID
• Secrets control — Vault/OpenBao backends, encrypted local storage, agent namespaces
• Audit logging — tamper-evident records written before the effect, not after

See the Security Model guide for full details, and the Containment Guide for current coverage and remaining gaps.

What is not claimed¶

A security page that lists only guarantees is asking to be believed. These limits are stated here rather than discovered later:

• Host configuration, worker images, the container runtime, operator-supplied inference endpoints and injected SDK implementations are trusted components, not verified ones.
• Containment is not complete across every entry point. Public browser execution, aggregate admission control, and automatic replay or recovery are unavailable or outside these contracts.
• A reasoning loop can reach Completed after a tool error or policy denial — inspect individual tool outcomes. A terminal write can fail after an effect occurred: an error is not a rollback. A missing or incomplete journal is absence of evidence, not evidence of success.
• Terminal approver identity is the local operator's effective UID — an OS account, not an independently verified individual. A review digest binds the exact request; it does not prove a person read it.
• Deterministic matched laboratory trials establish their individual scenarios. They do not supply a model escape rate.
• SOC 2, HIPAA and ISO 27001 are alignment targets the audit trail is designed for. No certification is held or implied.

All guides¶

Containment and governance

• Containment Guide — operator workflows, architecture, migration, remaining gaps
• Prepared Calls — exact-call authorization and Cedar request shape
• Approval Lifecycle — terminal, TUI and chat reviews
• Protected Run Audit — run identity, journal verification, incomplete outcomes
• Crash Inspection — verify interrupted runs and unresolved effects without replay
• Inline Effect Policies — the enforced DSL rule subset
• Command Isolation — worker configuration for tools and parsers
• Per-operation File Grants — declared inputs, bounded new outputs, parser isolation
• Docker Ownership — lifetime, cleanup and recovery
• Interactive Terminals — contained PTY sessions
• Shell Workspace — governed file and command tools in the TUI
• Managed CLI — running an external AI CLI as a contained child
• Governed Broker — the brokered tool-call API
• DSL Invocation Context — caller identity and frozen project root
• Scheduled Execution — invocation IDs and terminal results
• Invocation Idempotency — persistent CLI request identities and safe result retrieval

Core

• Getting Started — installation, configuration, first agent
• Symbi Shell (Beta) — interactive TUI for authoring, orchestration, remote attach
• Security Model — zero-trust architecture, policy enforcement, isolation tiers
• Runtime Architecture — runtime internals and execution model
• Reasoning Loop — ORGA cycle, policy gates, circuit breakers
• DSL Guide — agent definition language reference
• ToolClad — declarative tool contracts, argument validation, scope enforcement
• MCP Tools — governed Model Context Protocol access
• API Reference — HTTP API endpoints and configuration
• Scheduling — cron engine, delivery routing, dead-letter queues
• HTTP Input — webhook server, auth, rate limiting
• Firecracker Setup — Tier 3 kernel, rootfs and guest transport
• Managed Firecracker Host Service — optional jailer, host limits, watchdog deployment
• Session Types (Experimental) — inter-agent protocol conformance monitoring

Community and resources¶

• Agent guide: symbiont.dev/agent-guide.md — instructions for an AI coding agent doing your setup
• Packages: crates.io/crates/symbi | npm symbiont-sdk-js | PyPI symbiont-sdk
• SDKs: JavaScript/TypeScript | Python
• Plugins: Claude Code | Gemini CLI
• Issues: GitHub Issues
• License: Apache 2.0 (Community Edition)

Next steps¶