Getting Started¶

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

▶ 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.82+
• 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

Manual download: Download from GitHub Releases and add to your PATH.

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:

# Test the DSL parser
cd crates/dsl && cargo run && cargo test

# Test the runtime system
cd ../runtime && cargo test

# Run example agents
cargo run --example basic_agent
cargo run --example full_system

# Test the unified symbi CLI
cd ../.. && cargo run -- dsl --help
cargo run -- mcp --help

# Test with Docker container
docker run --rm symbi:latest --version
docker run --rm -v $(pwd):/workspace symbi:latest dsl parse --help
docker run --rm symbi:latest mcp --help

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: tier0 (none, dev only), tier1 (Docker), tier2 (gVisor / runsc), or tier3 (Firecracker microVM)

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 any profile:

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

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¶

# Parse and validate the agent definition
cargo run -- dsl parse my_agent.symbi

# Run the agent in the runtime
cd crates/runtime && cargo run --example basic_agent -- --agent ../../my_agent.symbi

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

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¶

# 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¶

Beyond the in-editor hooks, Symbiont can run Claude Code as a governed subprocess — the "Mode B" (ORGA-managed) path. An agent whose metadata declares executor = "claude_code" runs by spawning Claude Code under the runtime's CliExecutor instead of the LLM reasoning loop. The bundled code_reviewer agent is the reference example:

# Review a working tree with a governed Claude Code subprocess
symbi run code_reviewer --target /path/to/repo

# Bounds: --max-turns is the primary (cooperative) limit; --budget-timeout is a
# hard wall-clock backstop (graceful SIGTERM -> SIGKILL).
symbi run code_reviewer --target . --max-turns 12 --budget-timeout 15m

On each run Symbiont:

• evaluates the spawn through the policy Gate (fail-closed — allow it via a Cedar policy, or SYMBI_INSECURE_ALLOW_ALL=1 for local development);
• sets the env handshake (SYMBIONT_MANAGED=true, SYMBIONT_SESSION_ID, SYMBIONT_BUDGET_TOKENS, SYMBIONT_BUDGET_TIMEOUT, CLAUDE_PROJECT_DIR) so the symbi-claude-code plugin defers its hooks to the outer Gate;
• loads the plugin via --plugin-dir and wires the stdio symbi mcp back-channel via --mcp-config --strict-mcp-config;
• runs Claude Code headless (--print --output-format json --permission-mode dontAsk).

Auth: the subprocess uses Claude Code's own authentication — a logged-in session (claude /login) or ANTHROPIC_API_KEY. The cli-executor feature is on by default.

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"

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
cargo run -- dsl parse your_agent.symbi

# Enable debug logging
RUST_LOG=debug cd crates/runtime && cargo run --example basic_agent

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.