Skip to content

ThirdKeyAI/symbi-hybrid-stack

BranchesTags

Repository files navigation

symbi-hybrid-stack

Zero to secure agent fleet in 30 minutes.

A turnkey template for running Symbiont agent fleets in a desktop-primary, cloud-standby topology. Your local machine runs the coordinator via Docker Compose; Google Cloud Run provides failover and burst capacity.

Part of the ThirdKey trust stack: SchemaPin → AgentPin → Symbiont

┌─────────────────────────────────────────────────────────────────┐
│                      symbi-hybrid-stack                         │
│                                                                 │
│  ┌──────────── Desktop (primary) ────────────┐                  │
│  │                                           │                  │
│  │  Docker Compose                           │                  │
│  │  ┌─────────┐ ┌──────────┐ ┌────────┐      │                  │
│  │  │  Symbi  │ │  LanceDB │ │  a2ui  │      │                  │
│  │  │  :8081  │ │(embedded)│ │ :3001  │      │                  │
│  │  │  (HTTP) │ │          │ │(dashboard)    │                  │
│  │  └────┬────┘ └──────────┘ └────────┘      │                  │
│  │       │                                   │                  │
│  │  ┌────┴──────────┐                        │                  │
│  │  │  Cloudflare   │                        │                  │
│  │  │  Tunnel       │ ◄── zero-trust ingress │                  │
│  │  └───────────────┘                        │                  │
│  └───────────────────────────────────────────┘                  │
│                         │                                       │
│                    state sync                                   │
│                    (Litestream)                                 │
│                         │                                       │
│  ┌──────────── Cloud (standby) ──────────────┐                  │
│  │                                           │                  │
│  │  Google Cloud Run                         │                  │
│  │  ┌──────────────┐  ┌──────────────┐       │                  │
│  │  │ Coordinator  │  │   Workers    │       │                  │
│  │  │ (min=0,      │  │ (max=10,     │       │                  │
│  │  │  standby)    │  │  Pub/Sub)    │       │                  │
│  │  └──────────────┘  └──────────────┘       │                  │
│  │                                           │                  │
│  │  Artifact Registry │ Secret Manager       │                  │
│  │  GCS State Bucket  │ Cloud Logging        │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                 │
│  ┌──────────── Shared ───────────────────────┐                  │
│  │  AgentPin identity keys & trust bundles   │                  │
│  │  Agent DSL definitions                    │                  │
│  │  Lease schema for coordination            │                  │
│  └───────────────────────────────────────────┘                  │
└─────────────────────────────────────────────────────────────────┘

Prerequisites

  • Docker & Docker Compose v2
  • Bash 4+
  • An LLM API key (OpenRouter, OpenAI, or Anthropic)
  • (Optional) Cloudflare Tunnel for zero-trust ingress
  • (Optional) Google Cloud SDK + Terraform 1.5+ for cloud failover

Quick Start — Desktop Only (5 min)

One command to clone, configure, and start your agent fleet:

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

The installer checks prerequisites, generates an auth token, prompts for your LLM API key, pulls Docker images, and starts the stack.

Options:

# Install to a custom directory
curl -fsSL https://symbiont.dev/install.sh | bash -s -- --dir ~/my-fleet

# Clone and configure only, don't start services
curl -fsSL https://symbiont.dev/install.sh | bash -s -- --no-start
Manual setup (without the installer) 
# 1. Clone and enter the repo
git clone https://github.com/thirdkeyai/symbi-hybrid-stack.git
cd symbi-hybrid-stack

# 2. Initialize environment
make init

# 3. Edit .env with your LLM API key
$EDITOR .env

# 4. Start the desktop stack
make desktop-up

# 5. Verify everything is healthy
make verify

Your agent fleet is now running at http://localhost:8081. The coordinator manages task routing, health monitoring, and audit logging.

Add Cloud Failover (15 min)

# 1. Configure cloud environment
cp cloud/.env.example cloud/.env
$EDITOR cloud/.env   # Set GCP_PROJECT_ID, GCP_REGION, etc.

# 2. Deploy cloud standby
make cloud-deploy

# 3. Verify hybrid topology
make verify

The cloud coordinator starts at min-instances=0 (costs nothing at idle). Workers scale to 10 instances via Pub/Sub triggers.

To enable Litestream state replication between desktop and cloud:

# Set GCS_STATE_BUCKET in .env, then start with replication profile
make desktop-up-replicated

Scale Up (5 min)

Add new agents by creating DSL files in desktop/agents/:

# 1. Create a new agent
cp desktop/agents/data_processor.dsl desktop/agents/my_agent.dsl
$EDITOR desktop/agents/my_agent.dsl

# 2. Generate AgentPin credentials
make keygen

# 3. Restart to pick up changes
make desktop-down && make desktop-up

See shared/agents/README.md for the DSL capabilities reference.

Using Qdrant Instead of LanceDB

If you prefer Qdrant as the vector backend, use the Qdrant make target — it automatically configures the backend, host, and port:

make desktop-up-qdrant

Qdrant runs as a separate container and exposes port 6333 internally. See desktop/docker-compose.yml for the full service definition.

Project Structure

├── desktop/              # Docker Compose stack (primary)
│   ├── agents/           # Agent DSL definitions
│   ├── policies/         # Network, secrets, audit policies
│   ├── scripts/          # init, healthcheck, backup, stop
│   └── tunnel/           # Cloudflare Tunnel config
├── cloud/                # Google Cloud Run (standby)
│   ├── coordinator-standby/  # Standby coordinator service
│   ├── worker-agent/         # Burst worker service
│   ├── terraform/            # Infrastructure as code
│   └── scripts/              # deploy, failover, teardown
├── shared/               # Shared between desktop & cloud
│   ├── identity/         # AgentPin keys & trust bundles
│   ├── state/            # SQLite schema & sync config
│   └── agents/           # DSL documentation
├── security/             # Security docs & verification
├── examples/             # Migration guides & use cases
└── .github/              # CI/CD workflows

Makefile Targets

Target Description
make init First-run setup: copy .env, generate keys, pull images
make desktop-up Start desktop Docker Compose stack
make desktop-down Stop desktop stack gracefully
make cloud-deploy Deploy cloud standby via Terraform
make cloud-teardown Destroy cloud resources
make verify Run health checks and security validation
make keygen Generate/rotate AgentPin identity keys
make desktop-up-replicated Start desktop stack with Litestream GCS replication
make desktop-up-qdrant Start desktop stack with Qdrant vector backend
make logs Tail logs from all services

v1.5.0 Features

This stack leverages Symbiont v1.5.0 capabilities:

  • Embedded Vector Search — LanceDB replaces Qdrant as the default vector backend; no external service required. Qdrant remains available via --profile qdrant
  • Context Compaction — Automatic four-tier pipeline (summarize → compress → archive → truncate) manages context pressure at configurable thresholds
  • Composio MCP Integration — Optional Composio API key enables MCP tool integrations for agents
  • Multi-Model Token Counting — Accurate token budgeting across OpenRouter, OpenAI, and Anthropic models
  • Persistent Memory — Coordinator and compliance agents use memory {} blocks for Markdown-backed persistence with configurable retention
  • Webhook Verification — All webhook endpoints use webhook {} blocks with HMAC-SHA256 signature verification
  • Native Scheduling — Compliance checker runs on a schedule {} block (cron "0 6 * * *") — no external cron required
  • Metrics Telemetry — /api/v1/metrics endpoint with file-based export for monitoring

Security Model

Every agent in the fleet has a cryptographic identity via AgentPin:

  • ES256 keypairs with five discovery methods: trust bundles, local directories, chain resolvers, offline mode, and online .well-known endpoints
  • TOFU key pinning records public keys on first contact and rejects unexpected changes
  • Three-level revocation — per-credential, per-key, per-issuer — with offline and online distribution
  • Trust bundles for air-gapped and enterprise verification
  • Webhook signature verification — HMAC-SHA256 with constant-time comparison; built-in presets for GitHub, Stripe, and Slack
  • Audit logging of all agent actions with credential chains
  • Policy DSL for network egress, secret access, and audit rules

See security/SECURITY.md for the full trust model and security/threat-model.md for the threat matrix.

License

Apache 2.0 — Copyright (c) 2024-2026 Jascha Wanger / ThirdKey AI

About

A ready-to -launch hybrid local and Google Cloud Run Symbiont agents you can run virtually for free.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages