Getting Started¶

Running agents under containment? Start with the containment operator guide for execution prerequisites, approval changes and current coverage.

This guide will walk you through setting up Symbi and creating your first AI agent.

Upgrading from 1.x? Read the 2.0 migration guide before replacing an existing installation. Prompt caching and governed improvements remain optional.

▶ Watch the get-started walkthrough:

Prerequisites¶

What you need depends on how you install and run Symbi.

To run the pre-built binary¶

The pre-built binaries are already compiled — you do not need Rust, protobuf, or Git to install or run them. Install with Homebrew, the install script (curl), or a manual download from GitHub Releases.

• Docker is only needed at runtime if you execute agents under the default sandbox tier (tier1, Docker-backed). It is not needed to install Symbi or to run symbi init, symbi dsl, or symbi --version.

To build from source¶

Required only if you install via cargo install or build the repository yourself:

• Rust 1.89+
• protobuf-compiler (apt install protobuf-compiler on Ubuntu, brew install protobuf on macOS)
• Git (to clone the repository)

Optional¶

• symbi-claude-code (Claude Code governance plugin)
• symbi-gemini-cli (Gemini CLI governance extension)

Note: Vector search is built in. Symbi ships with LanceDB as an embedded vector database -- no external service required.

Installation¶

Option 1: Pre-Built Binaries (Quick Start)¶

Note: Pre-built binaries are tested but considered less reliable than cargo install or Docker.

macOS (Homebrew):

brew tap thirdkeyai/tap
brew install symbi

macOS / Linux (install script):

curl -fsSL https://raw.githubusercontent.com/ThirdKeyAI/Symbiont/main/scripts/install.sh | bash
export PATH="$HOME/.symbi/bin:$PATH"
symbi --version

The repository installer requires Bash, curl or wget, tar, and sha256sum or shasum. It reads the latest release's checksum manifest, selects exactly one versioned archive for the detected platform, and verifies its SHA-256 before extracting it into ~/.symbi/bin. Missing or ambiguous entries and checksum failures stop installation. To choose another root, set SYMBI_INSTALL_DIR on the bash process. Reload your shell or set PATH as above after installation.

Manual download: Download a specific version from GitHub Releases. Archives are available for Linux x86_64/ARM64, macOS ARM64 and Windows x86_64. The shell installer supports the Linux and macOS targets; use the ZIP archive on Windows. Follow release verification to check the signed checksum manifest, source commit and archive before adding the binary to PATH.

Installing a macOS or Windows binary does not provide Landlock isolation. Landlock requires Linux ABI 6+, seccomp, unprivileged user/mount/network namespaces, cgroup v2 delegation and a systemd user manager. Select it per project with symbi init --sandbox landlock; see Linux setup.

Option 2: Docker (Recommended)¶

The fastest way to get a working runtime is to let the container scaffold the project for you:

# 1. Scaffold symbiont.toml, agents/, policies/, docker-compose.yml, and
#    a .env with a freshly generated SYMBIONT_MASTER_KEY.
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace

# 2. Start the runtime. Reads .env automatically.
docker compose up

Runtime API is now on http://localhost:8080 and HTTP Input on http://localhost:8081.

If you'd rather work from a clone (to build the image yourself or run tests):

git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont

# Build the unified symbi container
docker build -t symbi:latest .

# Run the development environment
docker run --rm -it -v $(pwd):/workspace symbi:latest bash

Option 3: Local Installation¶

For local development:

# Clone the repository
git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont

# Install Rust dependencies and build
cargo build --release

# Run tests to verify installation
cargo test

Verify Installation¶

Test that everything is working correctly.

Installed binary or Docker:

symbi --version
symbi dsl --help
symbi mcp --help

# ...or via the published Docker image
docker run --rm ghcr.io/thirdkeyai/symbi:latest --version
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest dsl --help

From a source clone:

# Test the DSL parser and the runtime
cargo test -p symbi-dsl
cargo test -p symbi-runtime

# Run example agents
cargo run -p symbi-runtime --example basic_agent
cargo run -p symbi-runtime --example full_system

# Exercise the unified symbi CLI
cargo run -- dsl --help
cargo run -- mcp --help

Try it without an API key¶

Two things work offline, before you configure any model provider. Both demonstrate what Symbiont actually does, so start here.

Evaluate a policy. The Cedar gate is the same one the runtime wires into the live reasoning loop:

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

Define a governed tool and dry-run it. Argument types, scope limits and injection checks are enforced before anything 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]

Running an agent needs a model provider — either a cloud key or a local model, both covered below.

Project Initialization¶

The fastest way to start a new Symbiont project is symbi init:

symbi init

This launches an interactive wizard that guides you through: - Profile selection: minimal, assistant, dev-agent, or multi-agent - SchemaPin mode: tofu (Trust-On-First-Use), strict, or disabled - Sandbox tier: landlock (native Linux), tier0 (none, dev only), tier1 (Docker), tier2 (gVisor / runsc), or tier3 (Firecracker microVM)

With --sandbox landlock --profile dev-agent, the wizard also asks for the source repository, installed Claude Code executable, Messages-compatible inference URL, model and credential environment variable name. It generates a read-only review setup in a separate, empty control directory. Noninteractive callers must supply --source, --managed-executable, --inference-url, --inference-model and --inference-key-env. See Linux developer onboarding.

What init produces¶

Every run writes:

Pass --no-docker-compose to skip the compose file, and --dir <PATH> to write into a directory other than the current one (essential inside a Docker container — see below).

Non-interactive mode¶

For CI/CD or scripted setups:

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

Running init inside Docker¶

Because the image's WORKDIR is /var/lib/symbi, use --dir to write into your mounted volume:

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

That populates the host's current directory with the full project tree.

Profiles¶

Importing from the catalog¶

Import pre-built agents alongside general profiles (the read-only Landlock development initializer does not combine catalog imports):

symbi init --profile minimal --no-interact
symbi init --catalog assistant,dev

List available catalog agents:

symbi init --catalog list

After initialization, validate and run:

symbi dsl -f agents/assistant.symbi   # validate your agent
symbi run assistant -i '{"query": "hello"}'  # test a single agent
symbi up                             # start the runtime locally
docker compose up                    # ...or start it in Docker (reads .env)

Running a single agent¶

Use symbi run to execute one agent without starting the full runtime server:

symbi run <agent-name-or-file> --input <json>

The command resolves agent names by searching: direct path, then agents/ directory. It sets up cloud inference from environment variables (OPENROUTER_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY), runs the ORGA reasoning loop, and exits.

symbi run assistant -i 'Summarize this document'
symbi run agents/recon.symbi -i '{"target": "10.0.1.5"}' --max-iterations 5

Tool commands, parsers, MCP and PTY execution require the selected container backend, a cached image with the declared executables, and explicit data mounts. Unavailable backends cannot fall back to host execution. Selected agent settings and project defaults are checked before inference. Runs also require protected .symbiont/governed/ storage and print their public audit reference. See command configuration and run audit.

Starting from a template (symbi new)¶

symbi init scaffolds a generic project; symbi new scaffolds a project around one of several task-shaped templates. Useful when you know the kind of agent you need before you know the agents you need.

symbi new --list                     # show available templates
symbi new <template> <project-name>  # create a new project from a template

Shipped templates:

symbi new and symbi init are complementary: new gives you a task-specific starting point, init (+ --catalog) gives you a governance-specific one. You can also combine — scaffold with new, then symbi init --catalog ... to pull in additional pre-built agents from the catalogue.

Your First Agent¶

Let's create a simple data analysis agent to understand the basics of Symbi.

1. Create Agent Definition¶

Create a new file my_agent.symbi:

metadata {
    version = "1.0.0"
    author = "your-name"
    description = "My first Symbi agent"
}

agent greet_user(name: String) -> String {
    capabilities = ["greeting", "text_processing"]

    policy safe_greeting {
        allow: read(name) if name.length <= 100
        deny: store(name) if name.contains_sensitive_data
        audit: all_operations with signature
    }

    with memory = "ephemeral", privacy = "low" {
        if (validate_name(name)) {
            greeting = format_greeting(name);
            audit_log("greeting_generated", greeting.metadata);
            return greeting;
        } else {
            return "Hello, anonymous user!";
        }
    }
}

2. Run the Agent¶

First, validate the agent definition:

symbi dsl -f my_agent.symbi

Then run it. symbi run executes the agent through the ORGA reasoning loop, which needs a model provider — export one of OPENROUTER_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY first:

export OPENROUTER_API_KEY=sk-...            # or OPENAI_API_KEY / ANTHROPIC_API_KEY
symbi run my_agent.symbi -i '{"name": "World"}'

Using a local model¶

The provider does not have to be a cloud service. Point OPENAI_BASE_URL at any OpenAI-compatible server — Ollama, vLLM, LM Studio and llama.cpp all expose one — and no cloud key is involved:

export OPENAI_API_KEY=ollama                     # any non-empty value
export OPENAI_BASE_URL=http://localhost:11434/v1
export CHAT_MODEL=llama3.1

symbi run my_agent.symbi -i '{"name": "World"}'

The same three variables work for symbi up. Each provider has its own base URL override — OPENROUTER_BASE_URL, OPENAI_BASE_URL, ANTHROPIC_BASE_URL — and the model is chosen with CHAT_MODEL (OpenAI-compatible), OPENROUTER_MODEL, or ANTHROPIC_MODEL.

Symbiont warns when a base URL uses plaintext http://, since the key travels with the request. That is expected for a model on your own machine.

Metrics¶

The runtime always serves GET /api/v1/metrics. OTLP export to a collector is separate: it sits behind the metrics feature and is off in the default build to keep it lean. Enable it when you need one:

cargo install symbi --features metrics

Export settings (service name, interval) come from the runtime's metrics configuration rather than environment variables.

Understanding the DSL¶

The Symbi DSL has several key components:

Metadata Block¶

metadata {
    version = "1.0.0"
    author = "developer"
    description = "Agent description"
}

Provides essential information about your agent for documentation and runtime management.

Agent Definition¶

agent agent_name(parameter: Type) -> ReturnType {
    capabilities = ["capability1", "capability2"]
    // agent implementation
}

Defines the agent's interface, capabilities, and behavior.

Policy Definitions¶

policy policy_name {
    allow: action_list if condition
    deny: action_list if condition
    audit: operation_type with audit_method
}

Declarative security policies that are enforced at runtime.

Execution Context¶

with memory = "persistent", privacy = "high" {
    // agent implementation
}

Specifies runtime configuration for memory management and privacy requirements.

Next Steps¶

Explore Examples¶

The repository includes several example agents:

# Basic agent example
cd crates/runtime && cargo run --example basic_agent

# Full system demonstration
cd crates/runtime && cargo run --example full_system

# Context and memory example
cd crates/runtime && cargo run --example context_example

# RAG-powered agent
cd crates/runtime && cargo run --example rag_example

Enable Advanced Features¶

HTTP API (Optional)¶

# Enable the HTTP API feature
cd crates/runtime && cargo build --features http-api

# Run with API endpoints
cd crates/runtime && cargo run --features http-api --example full_system

Key API Endpoints: - GET /api/v1/health - Health check and system status - GET /api/v1/agents - List all active agents with real-time execution status - GET /api/v1/agents/{id}/status - Get detailed agent execution metrics - POST /api/v1/workflows/execute - Execute workflows

New Agent Management Features: - Real-time process monitoring and health checks - Graceful shutdown capabilities for running agents - Comprehensive execution metrics and resource usage tracking - Support for different execution modes (ephemeral, persistent, scheduled, event-driven)

Cloud LLM Inference¶

Connect to cloud LLM providers via OpenRouter:

# Enable cloud inference
cargo build --features cloud-llm

# Set API key and model
export OPENROUTER_API_KEY="sk-or-..."
export OPENROUTER_MODEL="google/gemini-2.0-flash-001"  # optional

AWS Bedrock Provider¶

Use AWS Bedrock-hosted models via the Converse API:

# Enable Bedrock provider
cargo build --features bedrock

# For reasoning-loop inference, also enable cloud-llm
cargo build --features bedrock,cloud-llm

# Set Bedrock model and region
export BEDROCK_MODEL_ID="anthropic.claude-3-5-sonnet-20241022-v2:0"
export AWS_REGION="us-east-1"

# Credentials from standard AWS chain (env, profile, or role)
export AWS_ACCESS_KEY_ID="<your-key>"
export AWS_SECRET_ACCESS_KEY="<your-secret>"

The Bedrock provider integrates with LlmClient and CloudInferenceProvider for agent reasoning. It uses the Converse API (non-streaming) with tool-use support for tool-capable models. Credentials follow the standard AWS credential chain: environment variables, shared credentials file, or IAM role.

For the reasoning loop's symbi run / symbi up with Bedrock, always build with both bedrock and cloud-llm features.

Standalone Agent Mode¶

One-liner for cloud-native agents with LLM inference:

cargo build --features standalone-agent
# Enables: cloud-llm

Note: Composio MCP and SymbiBot integration were removed in this version due to security concerns — see SECURITY_AUDIT.md C3 for context.

Advanced Reasoning Primitives¶

Enable tool curation, stuck-loop detection, context pre-fetch, and scoped conventions:

cargo build --features orga-adaptive

See the orga-adaptive guide for full documentation.

Cedar Policy Engine¶

Formal authorization with the Cedar policy language. Default-on since v1.14.x: published symbi binaries (crates.io, Docker, GitHub Release tarballs) include Cedar, and symbi up / symbi run auto-wire CedarPolicyGate from policies/*.cedar files at startup; if none are present the runtime falls through to the fail-closed DefaultPolicyGate. To build without Cedar (e.g. when you intend to wire OpaPolicyGateBridge or a custom ReasoningPolicyGate instead), use:

cargo build --no-default-features --features "keychain,vector-lancedb"  # drop cedar

Vector Database (Built-in)¶

Symbi includes LanceDB as a zero-config embedded vector database. Semantic search and RAG work out of the box -- no separate service to start:

# Run agent with RAG capabilities (vector search just works)
cd crates/runtime && cargo run --example rag_example

# Test context management with advanced search
cd crates/runtime && cargo run --example context_example

Minimal build: LanceDB is included by default but can be excluded for lighter binaries: cargo build --no-default-features. The runtime gracefully falls back to a no-op vector backend.

Scaled deployments: Qdrant is available as an optional backend. Build with --features vector-qdrant and set SYMBIONT_VECTOR_BACKEND=qdrant.

Context Management Features: - Multi-Modal Search: Keyword, temporal, similarity, and hybrid search modes - Importance Calculation: Sophisticated scoring algorithm considering access patterns, recency, and user feedback - Access Control: Policy engine integration with agent-scoped access controls - Automatic Archiving: Retention policies with compressed storage and cleanup - Knowledge Sharing: Secure cross-agent knowledge sharing with trust scores

Feature Flags Reference¶

The Default column is crates/runtime's own default feature set. The rows marked "always on in symbi" are requested unconditionally by the published symbi binary (see the symbi-runtime dependency in the root Cargo.toml), so they are present in a released binary whether or not you pass --features, and --no-default-features on the CLI does not remove them. Build the library directly if you need them absent.

# Build with specific features
cargo build --features "cloud-llm,orga-adaptive,cedar"

# Build with everything
cargo build --features full

AI Assistant Plugins¶

Symbiont provides first-party governance plugins for popular AI coding assistants with three progressive protection tiers:

1. Awareness (default) — advisory logging of all state-modifying tool calls
2. Protection — blocking hook enforces a local deny list (.symbiont/local-policy.toml)
3. Governance — Cedar policy evaluation when symbi is on PATH

The deny list config is tool-agnostic — the same .symbiont/local-policy.toml works with both plugins:

[deny]
paths = [".env", ".ssh/", ".aws/"]
commands = ["rm -rf", "git push --force"]
branches = ["main", "master", "production"]

Claude Code¶

# Install from marketplace
/plugin marketplace add https://github.com/thirdkeyai/symbi-claude-code

# Available skills: /symbi-init, /symbi-policy, /symbi-verify, /symbi-audit, /symbi-dsl

See symbi-claude-code for details.

Mode B: governed Claude Code subprocess¶

An agent with metadata { executor = "claude_code" } runs its CLI child in the selected Docker/gVisor container with scratch storage and private runtime inference/tool channels. The bundled code_reviewer is the reference agent. First configure a cached CLI/Python image, explicit backend source mounts, registered ToolClad tools and Cedar policies, and [managed_cli.inference]. See managed CLI containment for a complete example.

# /srv/source must map to an explicit backend mount in the control project.
symbi run code_reviewer --target /srv/source --max-turns 12 --budget-timeout 15m

# Add operator review for tools that require approval.
symbi run code_reviewer --target /srv/source --approval-terminal

The child receives no direct source mount, external network access, host login state or provider credential. Registered tools broker allowed file/Git access. Built-in tools and automatic discovery are disabled. Every action requires runtime authorization; a spawn approval does not authorize subsequent actions. Plugins are not loaded and --plugin-dir is rejected.

Required signed session journals live in private .symbiont/governed/ storage. The runtime prints the public verification key. Missing approval, unsafe audit storage, an unavailable backend or failed cleanup cannot silently report success. Inference responses are buffered, including SSE, so streamed output is delayed.

Gemini CLI¶

# Install extension
gemini extensions install https://github.com/thirdkeyai/symbi-gemini-cli

The Gemini CLI extension provides additional defense-in-depth via excludeTools manifest blocking and native policies/*.toml enforcement at the platform level.

See symbi-gemini-cli for details.

Configuration¶

Environment Variables¶

Set up your environment for optimal performance:

# Required: 32-byte hex key used to encrypt persistent state.
# Generate with: openssl rand -hex 32
# `symbi init` writes one into .env automatically, and `symbi` auto-loads
# .env from the working directory — so in a scaffolded project you don't
# need to export it by hand. The line below is only for ad-hoc shells.
export SYMBIONT_MASTER_KEY="..."

# Basic configuration
export SYMBI_LOG_LEVEL=info
export SYMBI_RUNTIME_MODE=development

# Vector search works out of the box with the built-in LanceDB backend.
# To use Qdrant instead (optional, enable the `vector-qdrant` feature):
# export SYMBIONT_VECTOR_BACKEND=qdrant
# export QDRANT_URL=http://localhost:6333

# MCP integration (optional)
export MCP_SERVER_URLS="http://localhost:8080"

Security-related Environment Variables (post-v1.13.0 audit)¶

The following environment variables were removed:

• SYMBIONT_ALLOW_NO_JWT_AUDIENCE — the JWT verifier now always requires aud. (Removed in the post-v1.13.0 audit; was an unsafe escape hatch.)
• COMPOSIO_API_KEY, COMPOSIO_MCP_URL — the Composio MCP integration was removed entirely. See SECURITY_AUDIT.md C3.

Tool Contracts (ToolClad)¶

Define governed tool contracts in the tools/ directory:

symbi tools init my_tool          # create a starter manifest
symbi tools validate              # validate all manifests
symbi tools test my_tool --arg target=10.0.1.5   # dry-run with args

See the ToolClad guide for the full manifest format, execution modes, and scope enforcement.

Runtime Configuration¶

Create a symbi.toml configuration file:

[runtime]
max_agents = 1000
memory_limit_mb = 512
execution_timeout_seconds = 300

[security]
default_sandbox_tier = "docker"
audit_enabled = true
policy_enforcement = "strict"

[vector_db]
enabled = true
backend = "lancedb"              # default; also supports "qdrant"
collection_name = "symbi_knowledge"
# url = "http://localhost:6333"  # only needed when backend = "qdrant"

Human-in-the-loop approvals¶

Manifest/subcommand approval requirements remain mandatory even when Cedar allows a call. The shared queue holds each request until an authorized decision, expiry or cancellation. A stalled notifier cannot block another approval surface.

• Ordinary/managed CLI: add --approval-terminal, optionally with --approval-timeout 120 (1–3600 seconds). Review the complete escaped JSON and enter approve <request-id> exactly on the controlling terminal. Without the flag, approval-required calls fail closed.
• REST: authenticated GET /api/v1/approvals, POST /api/v1/approvals/{id}/approve and .../deny resolve pending requests.
• Shell: Ctrl+G opens the Gate panel even during a busy turn. Select with ↑/↓, press Enter to review the full request, scroll, then press a or d. /gate also opens the panel. A list row alone cannot approve.
• Chat: an allowlisted sender uses /symbi gate show <id>, then copies /symbi gate approve <id> <review-digest> from the complete review, or sends /symbi gate deny <id>. ID-only approvals are rejected. Oversized messages need another attached review surface.

Changed, expired or removed requests require a fresh review. The TUI reports resolution errors and unknown outcomes explicitly. Approval is permission to continue through the gate; verify actual execution in the signed run audit. Slack requires a nonempty signing secret and valid callback signatures in every environment. The former unsigned-callback override is no longer supported. See approval lifecycle for limits and trust assumptions.

Configure the timeout and chat approval channels in symbiont.toml:

[escalation]
timeout_seconds = 120

[[escalation.approval_channels]]
platform   = "slack"
channel_id = "C0APPROVERS"
approvers  = ["U0ALICE", "U0BOB"]   # allowlisted sender ids; empty = nobody may approve via chat

Common Issues¶

Docker Issues¶

Problem: Docker build fails with permission errors

# Solution: Ensure Docker daemon is running and user has permissions
sudo systemctl start docker
sudo usermod -aG docker $USER

Problem: Container exits immediately

# Solution: Check Docker logs
docker logs <container_id>

Rust Build Issues¶

Problem: Cargo build fails with dependency errors

# Solution: Update Rust and clean build cache
rustup update
cargo clean
cargo build

Problem: Missing system dependencies

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev

# macOS
brew install pkg-config openssl

Runtime Issues¶

Problem: Agent fails to start

# Check agent definition syntax
symbi dsl -f your_agent.symbi

# Enable debug logging
RUST_LOG=debug symbi run your_agent.symbi -i '{}'

Getting Help¶

Documentation¶

• DSL Guide - Complete DSL reference
• Runtime Architecture - System architecture details
• Security Model - Security and policy documentation

Community Support¶

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Complete API Reference

Debug Mode¶

For troubleshooting, enable verbose logging:

# Enable debug logging
export RUST_LOG=symbi=debug

# Run with detailed output
cd crates/runtime && cargo run --example basic_agent 2>&1 | tee debug.log

What's Next?¶

Now that you have Symbi running, explore these advanced topics:

1. DSL Guide - Learn advanced DSL features
2. Reasoning Loop Guide - Understand the ORGA cycle
3. Advanced Reasoning (orga-adaptive) - Tool curation, stuck-loop detection, pre-hydration
4. Runtime Architecture - Understand the system internals
5. Security Model - Implement security policies
6. Contributing - Contribute to the project

Ready to build something amazing? Start with our example projects or dive into the complete specification.