Getting Started¶

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

Prerequisites¶

Before getting started with Symbi, ensure you have the following installed:

Required Dependencies¶

• Docker (for containerized development)
• Rust 1.82+ (if building locally)
• protobuf-compiler (required for building — apt install protobuf-compiler on Ubuntu, brew install protobuf on macOS)
• Git (for cloning the repository)

Optional Dependencies¶

• 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 started is using Docker:

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

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

# Or use pre-built container
docker pull ghcr.io/thirdkeyai/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), tier1 (Docker), or tier2 (gVisor)

Non-interactive mode¶

For CI/CD or scripted setups:

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

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.dsl   # validate your agent
symbi run assistant -i '{"query": "hello"}'  # test a single agent
symbi up                             # start the full runtime

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.dsl -i '{"target": "10.0.1.5"}' --max-iterations 5

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.dsl:

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.dsl

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

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 and Composio tool access:

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

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:

cargo build --features 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.

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:

# 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, enterprise):
# export SYMBIONT_VECTOR_BACKEND=qdrant
# export QDRANT_URL=http://localhost:6333

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

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.dsl

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