Architecture

High-level reference for Tahyi’s components. For the conceptual model, see Core Concepts. For execution flow, see How it Works.

Component map

┌──────────────────────────────────────────────────────────┐
│                    Control plane                         │
│  Dashboard · Docs · API · Audit log · Policy engine      │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                 Coordination layer                       │
│  Tasks · Context · Handoffs · Heartbeats · Safety gates  │
└──────┬──────────┬──────────┬──────────┬───────────────────┘
       │          │          │          │
  ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ ┌────▼───┐
  │ Deploy │ │ Monitor│ │ Observe│ │  DBA   │
  │ agent  │ │ agent  │ │ agent  │ │ agent  │
  └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
      │          │          │          │
      └──────────┴──────────┴──────────┘
                         │
              ┌──────────▼──────────┐
              │  Target environment │
              │  (cluster / account)│
              └─────────────────────┘

Control plane

The control plane is the self-hosted application you run locally or deploy to your infra:

Surface	Purpose
Dashboard	Swarm status, active tasks, approval queue, audit log viewer
Docs	This documentation site, served alongside the app
API	REST/JSON endpoints for the coordination layer
Audit log	Append-only store of plans, tool calls, and outcomes
Policy engine	Dry-run defaults, approval rules, blast-radius limits

Default local URL: http://localhost:4321 (port configurable via PORT in .env).

Coordination layer

The coordination layer is the operating system for specialist agents:

Subsystem	Responsibility
Task manager	Create, assign, track, and close bounded work units
Context broker	Pass environment state, policy, and history to agents on wake
Handoff router	Route follow-up work to the correct specialist
Heartbeat scheduler	Wake agents on schedule or on external trigger
Safety gate	Classify two-way vs one-way doors; pause for approval

Agents do not communicate directly — all routing flows through the coordination layer. This keeps handoffs inspectable and safety gates enforceable swarm-wide.

Specialist agents

Each specialist is a narrow expert with its own tool integrations, prompts, and policy scope. Specialists are replaceable — swapping one should not break unrelated domains.

See Agents for the founding specialist catalog.

Environments

An environment is a registered target the swarm operates against:

npx tahyi env register \
  --name staging \
  --type kubernetes \
  --kubeconfig ~/.kube/config

Field	Description
`name`	Human-readable identifier (e.g. `staging`, `prod-us-east`)
`type`	Environment kind — `kubernetes` in 0.1; more types post-GA
`credentials`	Injected via config — never stored in agent prompts

Start with non-production. Production environments require additional policy configuration (approval gates, blast-radius caps).

Data flow

Trigger creates a task in the coordination layer
Context broker assembles environment state + policy + history
Specialist wakes, plans, classifies actions
Safety gate routes two-way actions to execution, one-way to approval queue
Audit log records every step
Handoff router creates follow-up tasks for other specialists if needed

Deployment model

Tahyi is self-hosted. You run the control plane on your infrastructure:

Local dev: npm run dev (see Quickstart)
Production: Deploy the control plane to your cluster or VM — exact deployment guide ships with 0.1

No SaaS account required. No vendor lock-in.

Core Concepts — vocabulary and safety model
How it Works — execution loop
Agents — specialist catalog
Configuration — environment variables and settings