Getting Started

🌐 Other Languages

English 中文简体 Español Português 日本語 Deutsch

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

Table of contents

  1. Prerequisites
    1. Required Dependencies
    2. Optional Dependencies
  2. Installation
    1. Option 1: Pre-Built Binaries (Quick Start)
    2. Option 2: Docker (Recommended)
    3. Option 3: Local Installation
    4. Verify Installation
  3. Your First Agent
    1. 1. Create Agent Definition
    2. 2. Run the Agent
  4. Understanding the DSL
    1. Metadata Block
    2. Agent Definition
    3. Policy Definitions
    4. Execution Context
  5. Next Steps
    1. Explore Examples
    2. Enable Advanced Features
      1. HTTP API (Optional)
      2. Cloud LLM Inference
      3. Standalone Agent Mode
      4. Advanced Reasoning Primitives
      5. Cedar Policy Engine
      6. Vector Database (Built-in)
      7. Feature Flags Reference
  6. AI Assistant Plugins
    1. Claude Code
    2. Gemini CLI
  7. Configuration
    1. Environment Variables
    2. Runtime Configuration
  8. Common Issues
    1. Docker Issues
    2. Rust Build Issues
    3. Runtime Issues
  9. Getting Help
    1. Documentation
    2. Community Support
    3. Debug Mode
  10. What’s Next?

Prerequisites

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

Required Dependencies

  • Docker (for containerized development)
  • Rust 1.88+ (if building locally)
  • Git (for cloning the repository)

Optional Dependencies

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.

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

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

Enterprise option: For teams that need a dedicated vector database, Qdrant is available as an optional feature-gated backend. Set SYMBIONT_VECTOR_BACKEND=qdrant and QDRANT_URL to use it.

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

Feature Description Default
keychain OS keychain integration for secrets Yes
vector-lancedb LanceDB embedded vector backend Yes
vector-qdrant Qdrant distributed vector backend No
embedding-models Local embedding models via Candle No
http-api REST API with Swagger UI No
http-input Webhook server with JWT auth No
cloud-llm Cloud LLM inference (OpenRouter) No
composio Composio MCP tool integration No
standalone-agent Cloud LLM + Composio combo No
cedar Cedar policy engine No
orga-adaptive Advanced reasoning primitives No
cron Persistent cron scheduling No
native-sandbox Native process sandboxing No
metrics OpenTelemetry metrics/tracing No
full All features except enterprise No 
# 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"

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

Community Support

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.