Tadpole OS

Appearance

IMPORTANT

AI Assist Note (Knowledge Heritage): This document is part of the "Sovereign Reality" documentation.

  • @docs ARCHITECTURE:Documentation
  • Failure Path: Information drift, legacy terminology, or documentation mismatch.
  • Telemetry Link: Cross-reference with execution/parity_guard.py results.

AI Assist Note ​

Automated governance and architectural tracking.

🔍 Debugging & Observability ​

Traceability via parity_guard.py.

🚀 Tadpole OS — Getting Started Guide ​

Intelligence Level: Configuration: Standard Business Setup
Status: Verified Production-Ready
Version: 1.1.225
Last Hardened: 2026-04-17 (Alignment Patch)
Classification: Sovereign

📚 Table of Contents ​

🛡️ Secure Configuration (The Zero-Secrets Handshake) ​

To ensure your instance of Tadpole OS remains private and sovereign, you must supply your own API keys. Never commit your keys to version control.

1. Initialize Your Environment ​

  1. Copy the template: cp .env.example .env
  2. Open .env and generate a unique NEURAL_TOKEN (e.g., openssl rand -hex 32). This token secures the connection between your browser and the engine.

2. Supply Your Provider Keys ​

Add your keys to the following variables in .env:

3. Local-First (Zero Cost) Option ​

If you prefer not to use external APIs, install Ollama and set PRIVACY_MODE=true. This forces the engine to use local models for all reasoning tasks.

IMPORTANT

Your keys are only stored in .env. When you save provider configurations in the UI, the engine automatically sanitizes them and only stores metadata (URLs, model names) in the repo-committed JSON files.

🏗️ Hardware Requirements (Scaling Spec) ​

Tadpole OS is optimized for low-footprint Rust execution. Requirements scale linearly with agent count and mission complexity.

TierAgentsClustersMin RAMvCPUDeployment
Micro (Demo)1-211 GB1Hybrid
Standard (Office PC)2-91-22 GB2Hybrid
Cluster Max10-254+4 GB4Hybrid
ROBUST (PRO)25+Full8 GB+4-8Full Remote

TIP

Robust Recommendation: For high-vocal missions with real-time audio and massive fetch_url research, an 8GB / 4-vCPU instance ensures zero latency in the context bus and allows for full remote rebuilds without OOMs.

Step 1: Connect to the Operations Dashboard ​

  1. Open Tadpole OS in your browser:
    • Local Dev: http://localhost:5173 (Vite 8 + React 19)
    • Production (Local Server): http://<local-ip>:8000 (Axum)
  2. Go to ⚙️ Settings from the sidebar (bottom-left gear icon).
  3. Under Engine Connection, verify the TadpoleOS URL is set to your engine endpoint and the Neural Engine Access Token matches your .env value.
  4. Click Save Changes — the dashboard auto-reconnects immediately using the Lazy Singleton Socket protocol.
  5. In the Tab Bar, you can now open additional operational contexts (Missions, Hierarchy, etc.) without losing your current view.
  6. The top Ticker Header should show 🟢 ONLINE and display real-time engine telemetry.

TIP

Multi-Monitor Setup: Tadpole OS supports State-Preserved Detachment. Click the External Link icon on any tab to "pop out" that context into a dedicated portal window. This uses a shared JS heap for zero-latency cross-window synchronization.

Development Note: For reliable database persistence on Windows, ensure DATABASE_URL is an absolute path (e.g., sqlite:D:\TadpoleOS-Dev\data\tadpole.db). The default when DATABASE_URL is unset is data/tadpole.db relative to the engine working directory.

Step 2: Unlock the Neural Vault & Add Your Groq Provider ​

The Neural Vault is an encrypted vault that stores your API keys. You must unlock it before configuring providers.

  1. Go to Providers from the sidebar (under the Intelligence section)
  2. You'll see the NEURAL VAULT lock screen
  3. Enter a master password (this encrypts your keys locally) → click Commit Authorization
  4. You'll now see the Provider Cards section

Adding Groq as a Provider ​

  1. If Groq is already listed, click the Edit (pencil) icon on the Groq card
  2. If not listed, click + ADD PROVIDER at the bottom:
    • Name: Groq
    • Icon: ⚡ (or any emoji)
    • Click Create
  3. On the Groq provider card:
    • API Key: Paste your Groq API key
    • Base URL: https://api.groq.com/openai/v1
    • Protocol: OpenAI (OpenRT) — Groq uses OpenAI-compatible API
  4. Click Save on the provider card.
  5. Test Trace (Handshake): Click the "Test Trace" button to perform a real-time connectivity handshake. This verifies your API Key, Endpoint, and Protocol are valid before deployment.

TIP

The vault auto-locks after inactivity. Your key is encrypted with your master password and stored in the browser — it never leaves your machine.

Step 3: Deployment with Business Starter Kits (Optional) ​

For rapid SME deployment, Tadpole OS allows you to choose a Business Starter Kit (Marketing, Customer Success, Finance). See the full Starter Kits Guide for the current built-in kits and install paths.

Step 4: Local Intelligence (Local LLMs via Ollama) ​

  1. Follow the Qwen3.5-9B Local Integration Guide for detailed setup.
  2. Once configured, you can add local models similarly to the steps below.

Step 5: Add Models to the Registry ​

Still on the Providers page, scroll down to the Model Registry section.

  1. Click + ADD MODEL
  2. Fill in:
    • Model Name: llama-3.3-70b-versatile
    • Provider: Select Groq from the dropdown
    • RPM (optional): e.g., 30 — prevents exceeding Groq's free-tier rate limits
    • TPM (optional): e.g., 14000 — the engine will throttle automatically
  3. Click the ✓ checkmark to save

Recommended models to add:

Model NameProviderBest For
llama-3.3-70b-versatileGroqGeneral tasks, tool calling
llama-3.1-8b-instantGroqFast responses, simple tasks
qwen3.5:9bOllamaLocal Power, high logic fidelity

Repeat for each model you want available.

Step 6: Configure an Agent Node ​

  1. Go to Hierarchy from the sidebar
  2. You'll see the Neural Command Hierarchy — your agent org chart
  3. Click on any agent card (e.g., Agent of Nine, Tadpole, etc.)
  4. The Agent Config Panel slides open on the right

In the Config Panel: ​

  1. Identity Section (top):

    • Name: Give it a descriptive name (e.g., Research Bot)
    • Role: Select from the dropdown (e.g., Researcher, Engineer, Analyst)

  2. Cognition Tab (MCP Tools & Skills):

    • Skills & Workflows: Toggle standard skills like web_search or code_execute.
    • MCP Tools: Select external tools from the high-density grid. These are specifically designed for Model Context Protocol integration.
    • Model Settings: Configure model, provider, and temperature for each slot (agents support up to 3 model slots).

  3. Voice & Governance Tabs:

    • Voice: Configure TTS/STT identity and voice engine (supports gemini-live and standard OpenAI TTS).
    • Governance: Toggle the Requires Oversight flag (Junior Agent mode) and set persistent USD budget caps for this specific node.

  4. Click 💾 SAVE CONFIG at the bottom.

IMPORTANT

The save pushes your config to the Rust backend, so it persists across devices and restarts. You'll see Capability Badges appear on the agent's card in the Hierarchy view, showing the count of assigned tools.

Step 7: Bulk Capability Assignment (Skills Hub) ​

Instead of configuring agents one-by-one, you can assign tools to multiple agents simultaneously.

  1. Go to Skills from the sidebar (under the Intelligence section, indented below Agents).
  2. Select any Skill, Workflow, or MCP Tool.
  3. Click the "Assign to Agents" button in the details panel.
  4. Select all agents you want to receive this capability.
  5. Click Commit Assignments. The engine will bulk-sync the configurations live.

Step 8: Importing External Capabilities (.md) ​

Tadpole OS allows you to rapidly build your agent's library by importing existing documentation.

  1. Go to Skills.
  2. Click the "Import .md" button in the header.
  3. Select a .md file containing a skill or workflow definition.
  4. Review the Import Preview to verify the parsed logic and ID.
  5. Click Confirm Import. The capability is now available in your User Registry for assignment.

Step 9: Create and Execute a Mission ​

  1. Go to Missions from the sidebar
  2. Click + NEW MISSION in the top-right of the cluster sidebar
  3. Fill in:
    • Mission Name: e.g., Market Research Sprint
    • Department: Select the relevant department (e.g., Research)
  4. Click Create

Assign Agents to the Mission: ​

  1. Select your new mission in the sidebar (it'll highlight)
  2. In the Available Agents pool on the right, click + Assign next to each agent you want on this mission
  3. Hierarchical Recruitment: High-level agents (Alphas) can recruit ephemeral sub-agents. The engine uses modular specialists from runner/mission_tools.rs to delegate tasks with strategic context handoffs.
  4. Parallel Swarming (PERF-06): Tadpole OS utilizes FuturesUnordered to parallelize tool calls. Recruitment of multiple specialists happens simultaneously, reducing swarm startup latency by up to 80%.
  5. Swarm Pulse Visualizer: Toggle the "Neural Map" icon on the mission dashboard to see a real-time Force-Graph visualization of cluster connectivity, featuring 10Hz binary telemetry pulses.
  6. Neural Swarm Optimization: When you type an objective, the engine proactively suggests mission-specific templates via the Template Discovery Hub.
  7. Recursion Guard: To prevent circular token-burn, the engine enforces a configurable Max Swarm Depth (default: 5, set via MAX_SWARM_DEPTH in .env).
  8. Mission Analysis (Agent 99): Toggle the "Analysis" switch next to the Run button to trigger a post-mission debrief powered by LanceDB vector synthesis.

Step 10: Workspace & Cluster Management ​

Tadpole OS allows you to organize your swarm into Mission Clusters.

  • Defaults: The engine starts with 4 predefined clusters (Strategic Command, Strategic Ops, Core Intelligence, Applied Growth).
  • Custom Scaling: You can create new clusters or retire existing ones from the Missions page.
  • Persistence: Agent roles and system configurations are stored in the backend SQLite database (data/tadpole.db). Logical mission clusters are managed by the frontend in LocalStorage.
  • Physical Sandboxes: Each cluster maps to a dedicated directory in the backend ./workspaces/{clusterId} folder, ensuring file isolation.

Step 11: External Adapters & Workspace Tools ​

The engine can now connect to your local environment and external services.

Workspace File Operations ​

Agents with matching skills can read and write files within their cluster sandbox:

  • read_file: Read a file from the workspace (e.g., load a spec document).
  • write_file: Write a file to the workspace (e.g., save generated code).
  • list_files: List files in a workspace directory.
  • delete_file: Delete a file (requires Oversight Gate approval).

Files are stored under workspaces/<cluster-id>/ on the server. Each cluster is fully isolated.

Local Markdown Vault (Obsidian) ​

Enabled agents can use the archive_to_vault tool.

  1. Create a vault/ directory in the server-rs root.
  2. Agents will automatically append findings to files in this directory when requested.

Discord Notifications ​

  1. Add DISCORD_WEBHOOK="your_webhook_url" to your .env file.
  2. Use the notify_discord tool from an agent to alert your team.

Environment Security (.env) ​

Ensure your .env file in the root directory contains:

VariableDescriptionRequirement
DATABASE_URLPath to tadpole.dbAbsolute path REQUIRED on Windows (e.g., sqlite:D:\TadpoleOS-Dev\data\tadpole.db). Defaults to data/tadpole.db relative to engine CWD.
AUDIT_PRIVATE_KEYEd25519 Private Key (Hex)Recommended for production. Enables non-repudiation and tamper-evident Merkle logging.
NEURAL_TOKENEngine Access Token for WebSocket/API accessRequired — engine panics if neither NEURAL_TOKEN nor NEURAL_ENGINE_ACCESS_TOKEN is set.
NEURAL_ENGINE_ACCESS_TOKENAlias for NEURAL_TOKENCan be used instead of NEURAL_TOKEN. Engine checks this first.
VITE_NEURAL_TOKENFrontend token (Vite env var)Set to match NEURAL_TOKEN so the frontend auto-configures.
ALLOWED_ORIGINSComma-separated CORS originsDefault: http://localhost:5173
MAX_SWARM_DEPTHMaximum agent recursion/spawn depthDefault: 5
MAX_AGENTSMaximum agents in the registryDefault: 50
MAX_CLUSTERSMaximum active clustersDefault: 10
ANTHROPIC_API_KEYClaude Provider KeyOptional
OPENAI_API_KEYOpenAI Provider KeyOptional
GROQ_API_KEYGroq Provider KeyOptional
DEEPSEEK_API_KEYDeepSeek Provider KeyOptional
GOOGLE_API_KEYGoogle Gemini Provider KeyOptional
INCEPTION_API_KEYInception AI Provider KeyOptional
OLLAMA_HOSTLocal LLM EndpointDefault: http://localhost:11434
DISCORD_WEBHOOKDiscord notification URLRequired only for notify_discord tool
TADPOLE_NULL_PROVIDERSForces graceful provider degradationDev/Test only.
SME_SYNC_INTERVAL_MINSIngestion Worker sync frequency (minutes)Default: 30
PRIVACY_MODEBlock all cloud providers, enforce local-onlyDefault: false
AUTO_APPROVE_SAFE_SKILLSAuto-approve tools tagged as "safe"Default: true

Standardized Observability (HATEOAS) ​

All resource endpoints in Tadpole OS implement the HATEOAS pattern. Responses include a _links object, enabling self-discovery of related actions. Error responses strictly follow RFC 9457 (Problem Details) for consistent machine-readable debugging.

Step 12: SME Data Intelligence (Connectors & Workflows) ​

Tadpole OS includes a 4-phase data intelligence layer for SME onboarding.

Phase 1: Hybrid RAG ​

The Neural Memory engine (memory.rs) automatically combines vector similarity with keyword proximity scoring for higher-fidelity context retrieval. This is transparent — no configuration required.

Phase 2: Data Connectors (Background Sync) ​

  1. Go to Hierarchy → select an agent → open the Memory tab.
  2. In the Connector Config section, click + Add Source.
  3. Set Type to fs (file system) and URI to the directory to watch (e.g., /data/business-docs/).
  4. Click Save. The Ingestion Worker will begin crawling this directory at the interval set by SME_SYNC_INTERVAL_MINS.
  5. Monitor sync status (idle/syncing/error) in the Memory Section UI.

TIP

The Ingestion Worker uses a SyncManifest to track file modification times. Only new or changed files are re-embedded, minimizing compute costs.

Phase 3: Deterministic SOP Workflows ​

  1. Create a markdown file in data/workflows/ on the server (e.g., data/workflows/onboarding.md).
  2. Format it with numbered steps — each step becomes a discrete agent turn.
  3. Assign the workflow to an agent via the Cognition tab in the Agent Config Panel.
  4. When the agent receives a mission, the SOP Engine will execute each step in guaranteed order.

Phase 4: Document Parsing ​

The Data Connectors automatically use the Layout-Aware Parser (parser.rs) for all ingested files. Supported formats: .txt, .md, .csv, .pdf (text-layer). Documents are chunked with 25% overlap for optimal embedding quality.

Step 13: Send a Task & Get Results ​

Option A: From the Terminal Bar ​

The terminal bar is at the bottom of every page.

  1. Click the terminal input field
  2. Type a command:
    /send Research Bot Analyze the top 3 competitors in the AI agent space and summarize their pricing models
    Format: /send <agent-name> <your task message>
  3. Press Enter
  4. Watch the System Log on the dashboard — you'll see:
    • 📡 Task dispatched to Research Bot
    • Live agent status updates
    • The final response from the LLM

Option B: Command Palette (Global Nav) ​

  1. Press Cmd+K (Mac) or Ctrl+K (Windows) anywhere.
  2. Search for an Agent, Cluster, or Directive.
  3. Select an agent to instantly focus them in the chat interface.

Option C: From the OPS Dashboard ​

  1. Go to the Operations dashboard (home page)
  2. The Live Agent Status cards show real-time activity
  3. The System Log captures all responses and events.
  4. Discover Nodes: Click the "Discover Nodes" button in the Infra section to scan your local network for secondary Local Nodes. Discovered nodes will automatically appear in your dashboard for unified oversight.

Option D: Neural Sync (Voice-to-Swarm) ​

  1. Go to Voice Interface from the sidebar (under "Comms & Assets")
  2. Select Target: Choose an Agent (e.g., Agent of Nine) or a Mission Cluster.
  3. Click Start Sync → Speak your high-level objective clearly.
  4. Hands-Free Response: The speaker icon activates automatically. The agent (typically Agent of Nine) will transcribe your intent via Groq Whisper and then synthesize a strategic confirmation back to you via OpenAI TTS.
  5. Click End Sync once the verbal handshake is complete.

NOTE

If the agent's voice_engine is set to gemini-live, the Live Voice Hub overlay will activate for a persistent, low-latency bidirectional audio session.

🛠️ Useful Terminal Commands ​

CommandWhat it does
/send <agent> <message>Send a task to a specific agent
/pause <agent>Pause a running agent
/resume <agent>Resume a paused agent
/statusShow all agent statuses
/swarm statusInventory mission clusters
/clearClear the system log

🛠️ Maintenance & Integrity (Python Environment) ​

For advanced users and AI agents, the execution/ directory contains standardized tools for maintaining the "Intelligence Grade" of the codebase:

ScriptPurposeProtocol
python execution/verify_all.pyFull System AuditPerforms pre-flight checks on engine & services
python execution/parity_guard.pyIntegrity GateEnsures documentation matches backend routing

NOTE

All scripts in execution/ follow a strict [OK] / [FAIL] machine-readable reporting protocol for autonomous agents.

🧩 Troubleshooting ​

IssueFix
Dashboard shows OFFLINECheck that the engine is running (npm run engine or Docker container is up)
Agent returns no responseVerify the model exists in the Model Registry and the API key is valid
Neural Vault won't unlockThe vault creates a new encryption key on first use — use any password. If locked out, use Emergency Vault Reset at the bottom of the unlock screen.
Model dropdown is emptyGo to Providers → unlock vault → add models to the registry
Agent config doesn't saveCheck browser console — engine must be online for persistence to work
Tool-Calling fails (Groq)The engine includes Self-Healing Retries for Groq. Malformed tool syntax is automatically corrected in a second pass.
Agent is slow / rate limitedThe engine enforces rpm/tpm limits set on the model. The agent will wait for the quota window to reset rather than drop requests.
NEURAL_TOKEN panic on startEither NEURAL_TOKEN or NEURAL_ENGINE_ACCESS_TOKEN env var is required for the engine to start. Set it in your .env file.
Workspace file access deniedAgent tried to access a path outside its sandbox. Check cluster_id mapping and ensure no path traversal in the filename.
Database not found on WindowsUse an absolute path for DATABASE_URL, e.g., sqlite:D:\TadpoleOS-Dev\data\tadpole.db

🐸 Starter Swarm Configuration (Quick-Deploy) ​

This section provides a ready-to-use 3-agent swarm with concrete settings optimized for Groq's free tier. Follow this to have a working hierarchical swarm in under 5 minutes.

Agent Roster ​

AgentIDRoleModelProviderTemperatureBudgetSkills
Agent of Nine1CEOllama-3.3-70b-versatileGroq0.8$2.00issue_alpha_directive, web_search
Tadpole2COO (Alpha)llama-3.3-70b-versatileGroq0.6$3.00web_search, write_file, read_file, spawn_subagent
Elon3CTO (Specialist)llama-3.1-8b-instantGroq0.3$1.00code_execute, write_file, read_file, list_files

TIP

Why these settings?

  • Agent of Nine uses high temperature (0.8) for creative strategic thinking and delegation.
  • Tadpole (Alpha) gets medium temperature (0.6) for balanced coordination and the spawn_subagent skill for recruitment.
  • Elon (Specialist) runs a fast, cheap model at low temperature (0.3) for precise code execution.
  • Budget caps prevent runaway token spend on Groq's free tier.

Rate Limits (Groq Free Tier Safe) ​

Set these in the Providers → Model Registry:

ModelRPMTPM
llama-3.3-70b-versatile3014000
llama-3.1-8b-instant3014000

Applying via the UI ​

  1. Go to Hierarchy → click each agent card
  2. Set the Model, Temperature, and Budget as shown above
  3. Expand Skills & Workflows → toggle the listed skills for each agent
  4. Click 💾 SAVE CONFIG for each agent

Applying via API (curl) ​

If you prefer programmatic setup, here are the exact payloads:

Configure Agent of Nine (CEO):

bash
curl -X PUT http://localhost:8000/v1/agents/1 \
  -H "Authorization: Bearer YOUR_NEURAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "llama-3.3-70b-versatile",
    "provider": "groq",
    "temperature": 0.8,
    "budget_usd": 2.0,
    "skills": ["issue_alpha_directive", "web_search"]
  }'

Configure Tadpole (Alpha/COO):

bash
curl -X PUT http://localhost:8000/v1/agents/2 \
  -H "Authorization: Bearer YOUR_NEURAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "llama-3.3-70b-versatile",
    "provider": "groq",
    "temperature": 0.6,
    "budget_usd": 3.0,
    "skills": ["web_search", "write_file", "read_file", "spawn_subagent"]
  }'

Configure Elon (Specialist/CTO):

bash
curl -X PUT http://localhost:8000/v1/agents/3 \
  -H "Authorization: Bearer YOUR_NEURAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "llama-3.1-8b-instant",
    "provider": "groq",
    "temperature": 0.3,
    "budget_usd": 1.0,
    "skills": ["code_execute", "write_file", "read_file", "list_files"]
  }'

NOTE

Replace YOUR_NEURAL_TOKEN with the value from your .env file. There is no built-in development token anymore.

🎯 Showcase Mission: "Competitive Intelligence Swarm" ​

This mission demonstrates the full power of hierarchical swarming — strategic delegation, parallel research, file collaboration, and synthesis. Run this after applying the Starter Swarm configuration above.

Mission Overview ​

┌──────────────────────────────────────────────────────────┐
│  YOU (Operator)                                          │
│  "Analyze the top 3 AI agent frameworks and write        │
│   a competitive brief with code comparison."             │
└─────────────────────┬────────────────────────────────────┘
                      │ Neural Handoff
┌─────────────────────▼────────────────────────────────────┐
│  Agent of Nine (CEO) — Depth 0                           │
│  Refines intent → issues alpha directive to Tadpole      │
└─────────────────────┬────────────────────────────────────┘
                      │ issue_alpha_directive
┌─────────────────────▼────────────────────────────────────┐
│  Tadpole (Alpha/COO) — Depth 1                           │
│  Decomposes into parallel research tasks                 │
│  ├─ spawn_subagent("researcher_a") → CrewAI analysis     │
│  ├─ spawn_subagent("researcher_b") → AutoGen analysis    │
│  └─ Assigns Elon to code comparison                      │
└──────┬──────────────┬───────────────┬────────────────────┘
       │              │               │ (Parallel)
   ┌───▼───┐    ┌─────▼─────┐   ┌────▼─────────────────┐
   │Rsrchr A│    │ Rsrchr B  │   │  Elon (CTO) — D2     │
   │CrewAI  │    │ AutoGen   │   │  code_execute +       │
   │research│    │ research  │   │  write_file           │
   └───┬────┘    └─────┬─────┘   └────┬─────────────────┘
       │               │              │
       └───────────────┼──────────────┘
                       │ Results flow up
┌──────────────────────▼───────────────────────────────────┐
│  Tadpole (Alpha) — Synthesis                             │
│  Merges all findings → write_file("competitive_brief.md")│
└──────────────────────────────────────────────────────────┘

Step 1: Dispatch the Mission ​

From the Terminal Bar:

/send Agent of Nine Analyze the top 3 AI agent frameworks (CrewAI, AutoGen, LangGraph). For each, research their architecture, pricing, and developer experience. Then have our CTO write a Python code comparison showing how each framework defines a simple 2-agent team. Synthesize everything into a competitive_brief.md in our workspace.

Or via curl:

bash
curl -X POST http://localhost:8000/v1/agents/1/tasks \
  -H "Authorization: Bearer YOUR_NEURAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze the top 3 AI agent frameworks (CrewAI, AutoGen, LangGraph). For each, research their architecture, pricing, and developer experience. Then have our CTO write a Python code comparison showing how each framework defines a simple 2-agent team. Synthesize everything into a competitive_brief.md in our workspace.",
    "provider": "groq",
    "model_id": "llama-3.3-70b-versatile",
    "budget_usd": 2.0
  }'

Step 2: Watch the Swarm Execute ​

Open these dashboard views to observe the swarm in real-time:

ViewWhat You'll See
HierarchyAgent status lights change: idle → thinking → active as each node activates
MissionsThe cluster sidebar shows task assignments and handoff chains
OperationsLive token burn, cost tracking, and the System Log streaming agent outputs
OversightIf write_file or delete_file triggers, you'll see approval requests here

What Happens Under the Hood ​

  1. Agent of Nine receives the prompt, applies strategic reasoning, and fires issue_alpha_directive to Tadpole with a refined, tactical breakdown.
  2. Tadpole decomposes the directive into 3 parallel tasks:
    • Spawns Researcher A (ephemeral) → searches for CrewAI architecture and pricing
    • Spawns Researcher B (ephemeral) → searches for AutoGen architecture and pricing
    • Sends a direct task to Elon → write Python code comparing all 3 frameworks
  3. Parallel Swarming (PERF-06) kicks in — all 3 sub-tasks execute concurrently via FuturesUnordered.
  4. As results flow back, Tadpole's synthesis turn merges them and calls write_file("competitive_brief.md") to save the final deliverable.
  5. Cost and token metrics are tracked per-agent in real-time on the Operations Dashboard.

Expected Output ​

After ~30-60 seconds (depending on Groq load), you'll find:

  • workspaces/<cluster-id>/competitive_brief.md — The final synthesized report
  • System Log entries showing the full delegation chain with swarm lineage breadcrumbs
  • Per-agent cost breakdown on each hierarchy node card

Scaling This Pattern ​

AdjustmentHow
Add more researchersGive Tadpole more budget and increase MAX_SWARM_DEPTH in .env
Use multiple providersAssign Claude to Agent of Nine, Groq to specialists
Enable voice dispatchUse Voice Interface → Neural Sync instead of typing
Auto-approve safe toolsSet AUTO_APPROVE_SAFE_SKILLS=true in .env or toggle in Oversight Settings
Save as a templateUse "Promote to Role" on your configured agents

Step 14: Performance Analysis & Real-time Telemetry ​

Tadpole OS provides "Top Tier" observability into swarm health and technical performance.

1. Real-time Telemetry (Swarm Visualizer) ​

The Engine page (sidebar: "Engine" under Intelligence) features a high-performance Swarm Visualizer:

  • Binary Swarm Pulse: Driven by a 10Hz MessagePack stream (0x02 header) for sub-millisecond state parity.
  • Topology Map: Visualizes the swarm as a 2D force-graph, showing agent status and recruitment relationships.
  • Detach & Recall: Pop the visualizer into a dedicated window for persistent oversight during deep-context missions.
  • Fiscal Burn: Real-time USD/token tracking via the TPM indicator.
  • Swarm Density: Monitor agent instantiation relative to system capacity.

2. Performance Analysis (Benchmarks) ​

  1. Go to Benchmarks from the sidebar (under Intelligence).
  2. Timeline View: Review historical benchmark results (latency, throughput, status).
  3. Comparison Tool: Select any two runs to calculate performance deltas.
    • Example: Compare "Current" vs "Baseline" to identify code regressions or provider latency spikes.
  4. Target Enforcement: Metrics are color-coded against the technical specifications in Benchmark_Spec.md.

3. Neural Map (Graph Visualization) ​

Navigate to Neural Map in the sidebar for a live code intelligence graph — visual blast-radius analysis and symbol-level relationship mapping of the codebase.

Step 15: The Swarm Template Ecosystem ​

Instead of manually configuring agents, Tadpole OS allows you to instantly download full, industry-specific agent swarms.

  1. Go to Store from the sidebar (under Intelligence) — or access it via the Template Store banner at the bottom of the Settings page.
  2. Discover: Browse the store or use the fuzzy search to find templates tailored to your industry and company size (e.g., "Legal Contract Review", "Healthcare Patient Intake"). Filter by industry and headcount.
  3. Preview: Click Preview on any template card to inspect the full swarm.json configuration before committing.
  4. Install: Click Install Swarm. The engine uses native Git Cloning to securely fetch the template from github.com/DDS-Solutions/Tadpole-OS-Industry-Templates and unpacks it into your data/swarm_config directory.
  5. Local Privacy Shield / Oversight Approval: If the downloaded template requests powerful execution skills (like Shell Access or API payments), the engine will freeze initialization and require you (the Operator) to manually approve the skills, ensuring Zero-Trust security.

Once installed, the Rust engine "hot-loads" the template from your local /data/swarm_config/ directory, and your new specialized agents will immediately appear in the Hierarchy.

🏘️ Swarm Topology Guide (How Many Bunkers Do You Need?) ​

Not every deployment needs multiple nodes. Use this table to choose the right topology for your organization before configuring agents.

Company SizeRecommendation
1–15 peopleSingle swarm, always. The operational overhead of managing multiple Bunker nodes eliminates the value for small teams. One box, all agents.
15–50 peopleSingle swarm with logical cluster isolation. Use cluster_id scoping on agents and knowledge entries to create department boundaries — Finance, Sales, Ops — without the infrastructure complexity of multi-node. Still one box.
50–150 peopleMulti-swarm makes sense if you have someone technical. One Bunker per major department (3–4 nodes max). Each node runs its own engine instance; the Bunker Mesh (mDNS peer discovery) handles coordination automatically.
150+ peopleMulti-swarm with full mesh. You have IT staff, real compliance requirements, and the budget for dedicated hardware per department. The P2P Knowledge Sync and Gossip Relay layer handles cross-node intelligence sharing.

TIP

Start simple. A single Tadpole OS instance with well-scoped clusters handles most SMB use cases. You can always promote to multi-swarm later — the cluster_id fields on agents and the Knowledge Store are already designed to make that migration seamless.

NOTE

Multi-swarm compliance benefit: For regulated industries (finance, healthcare, legal), running sensitive data on a dedicated Bunker that never gossips to other nodes is a structural compliance advantage. Each node's Merkle audit trail is an independent, tamper-evident record.

🏗️ Architecture Quick Reference ​

┌─────────────────────────────────────┐
│         Your Browser (React)        │
│  Operations │ Hierarchy │ Missions  │
│  Providers  │ Oversight │ Settings  │
│  Skills     │ Engine    │ Store     │
└───────────────┬─────────────────────┘
                │ HTTP + WebSocket
┌───────────────▼─────────────────────┐
│       Axum Rust Engine :8000        │
│  Agent Registry │ Task Router       │
│  Oversight Gate │ Persistence       │
│  Skill Runner   │ MCP Host          │
└───────────────┬─────────────────────┘
                │ API Calls
┌───────────────▼─────────────────────┐
│        LLM Provider (Groq)          │
│  llama-3.3-70b │ llama-3.1-8b      │
└─────────────────────────────────────┘
                │
┌───────────────▼─────────────────────┐
│     SQLite (data/tadpole.db)        │
│  Agents │ Models │ Audit Trail      │
└─────────────────────────────────────┘

Sovereign Intelligence Architecture.

Copyright © 2024-present DDS Solutions