hector

██╗  ██╗███████╗ ██████╗████████╗ ██████╗ ██████╗ 
██║  ██║██╔════╝██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗
███████║█████╗  ██║        ██║   ██║   ██║██████╔╝
██╔══██║██╔══╝  ██║        ██║   ██║   ██║██╔══██╗
██║  ██║███████╗╚██████╗   ██║   ╚██████╔╝██║  ██║
╚═╝  ╚═╝╚══════╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝

Your agents. Your infrastructure. Your rules.

Hector is an open-source AI agent runtime built for teams that need full control over their AI infrastructure. One self-contained binary, one YAML config, production-ready defaults. Deploy on-premise, in air-gapped environments, or in any cloud. No external dependencies, no runtime interpreters, no mandatory cloud accounts.

Documentation · Studio · Config Ref · CLI Ref · API Ref

Why Hector?

• Single Binary. Zero Dependencies. A ~30MB Go executable with the visual Studio UI baked in. Copy it to a server and run. No interpreters, no virtualenvs, no package managers. Works out of the box on any Linux, macOS, or Windows host
• Self-Sovereign by Design: Deploy on-premise, in air-gapped networks, or behind your firewall. LLM keys stay on your machines, data never transits third-party infrastructure, and there is zero telemetry. MIT licensed, fully auditable
• Open Standards, Zero Lock-In: Built entirely on A2A protocol for agent interop and MCP for tool connectivity. Swap LLM providers (Anthropic, OpenAI, Gemini, Ollama) with a one-line config change. Your investment is portable
• Config-Driven Operations: Agents, orchestration patterns, RAG pipelines, guardrails, triggers, and notifications. All defined in YAML, all version-controllable, all reviewable in CI. Or use the fluent Go API for full programmatic control
• SQL-Backed Durability: Sessions, tasks, and checkpoints persist to SQLite or PostgreSQL. Survives restarts, enables fault recovery, and powers human-in-the-loop workflows with built-in state management
• Enterprise Security & Multi-Tenancy: JWKS/OIDC authentication, prompt injection detection, PII redaction, tool sandboxing, rate limiting, agent visibility controls, and full tenant isolation. All declarative, all without writing code

Quick Start

macOS / Linux:

curl -fsSL https://gohector.dev/install.sh | sh
hector serve

Windows (PowerShell):

irm https://gohector.dev/install.ps1 | iex
hector serve

Homebrew:

brew install verikod/tap/hector
hector serve

Docker:

docker run -p 8080:8080 ghcr.io/verikod/hector:latest serve

Open http://localhost:8080/ — an admin secret is printed in the terminal. Enter it to unlock Studio and configure LLM providers, create agents, and start chatting. No config files needed

**Homebrew:**

```bash
brew install verikod/tap/hector
hector serve

Docker:

docker run -p 8080:8080 ghcr.io/verikod/hector:latest serve

Open http://localhost:8080/ — an admin secret is printed in the terminal. Enter it to unlock Studio and configure LLM providers, create agents, and start chatting. No config files needed.

Hector Studio

Hector Studio is the web UI for designing, testing, and managing agents.

Try it online → — no install required. Connect to any Hector server.

• Visual Flow Builder: Drag-and-drop canvas with bi-directional YAML sync
• Integrated Chat: Streaming responses with tool-call trace view
• Resource Management: Configure LLMs, tools, and guardrails without editing YAML
• Cloud Integration: Provision and manage cloud-hosted instances with a license key

Studio is also embedded in release builds and served at /. For development builds:

# Option 1: Build a single binary with UI embedded (requires Node.js)
make build-release

# Option 2: Run Studio dev server (hot-reload for UI development)
cd studio && npm run dev   # → http://localhost:5173

See the Studio Guide for details.

Core Architecture

SQL-Backed Foundation

All runtime state persists to SQL (SQLite or PostgreSQL):

# SQLite (default)
hector serve --database sqlite://.hector/hector.db

# PostgreSQL
hector serve --database postgres://user:pass@localhost/hector

Multi-Tenant Architecture

A single Hector deployment can host multiple isolated apps via the Admin API (not file-based configs). Each app has:

• Isolated agent configurations
• Separate session and state storage
• Independent vector store collections
• Per-app JWT authentication

Admin API

Manage apps, sessions, and queue via REST endpoints. Requires --auth-secret for authentication.

hector serve --auth-secret "admin-secret"

App Management

Create App:

curl -X POST http://localhost:8080/admin/apps \
  -H "Authorization: Bearer admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer-support", "config_json": "{...}"}'

# Response includes JWT for app authentication
{
  "app": {"id": "abc123", "name": "customer-support"},
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}

Session Management

Queue Management

JWKS Endpoint

# Public key for JWT verification
curl http://localhost:8080/admin/jwks

Agent Capabilities

Agent Types

Multi-Agent Patterns

agents:
  # Agent-as-tool: Call other agents like functions
  orchestrator:
    llm: default
    agent_tools: [researcher, writer]

  # Sub-agent delegation: Transfer control
  manager:
    llm: default
    sub_agents: [analyst, reporter]

  # Conditional routing
  router:
    type: conditional
    condition_agent: classifier
    condition_field: category
    on_true_agent: sales
    on_false_response: Redirecting to support...

Instruction Templating

Dynamic instruction resolution from session state:

agents:
  assistant:
    instruction: |
      Hello {user:name}, you're working on {app:project}.
      
      Context: {artifact.context.md}
      
      Previous summary: {temp:last_summary?}

Automation & Integration

Scheduled Triggers

Run agents on cron schedules with timezone support:

agents:
  daily_report:
    llm: default
    instruction: Generate the daily summary report.
    trigger:
      type: schedule
      cron: "0 9 * * *"  # Daily at 9am
      timezone: America/New_York
      input: "Generate report for {{.Date}}"

Webhook Triggers

Invoke agents via HTTP with payload transformation:

agents:
  github_handler:
    llm: default
    trigger:
      type: webhook
      path: /webhooks/github
      methods: [POST]
      secret: ${WEBHOOK_SECRET}
      signature_header: X-Hub-Signature-256
      webhook_input:
        template: "PR #{{.number}} by {{.user.login}}: {{.title}}"
        session_id: "pr-{{.number}}"
        extract_fields:
          - path: pull_request.title
            as: title
      response:
        mode: async  # sync | async | callback

Outbound Notifications

A2A-compliant push notifications on agent events:

agents:
  processor:
    llm: default
    notifications:
      - id: slack-notify
        url: https://hooks.slack.com/services/xxx
        events: [task_completed, task_failed]
        headers:
          Content-Type: application/json
        payload:
          template: |
            {"text": "Agent {{.AgentName}}: {{.Status}}"}
        retry:
          max_attempts: 3
          initial_delay: 1s
          max_delay: 30s

Tool Ecosystem

MCP Protocol Support

Native Model Context Protocol with all transports:

tools:
  filesystem:
    type: mcp
    transport: stdio
    command: npx
    args: [-y, "@modelcontextprotocol/server-filesystem", "./data"]
    filter: [read_file, write_file]  # Limit exposed tools

  remote_mcp:
    type: mcp
    transport: sse
    url: http://localhost:8000/mcp

Built-in Tools

Command Tool with Security

tools:
  shell:
    type: command
    allowed_commands: [ls, cat, grep, find]
    denied_commands: [rm, sudo]
    working_directory: /app/workspace
    max_execution_time: 30s
    require_approval: true
    approval_prompt: "Allow command execution?"

RAG Pipeline

Enterprise-grade retrieval-augmented generation:

Document Sources

Advanced Retrieval

document_stores:
  knowledge:
    source:
      type: directory
      include: ["**/*.md", "**/*.pdf"]
      exclude: ["**/node_modules/**"]
    
    chunking:
      strategy: semantic
      size: 1000
      overlap: 200
    
    search:
      top_k: 10
      threshold: 0.7
      enable_hyde: true      # Hypothetical document embeddings
      enable_rerank: true    # LLM reranking
      enable_multi_query: true  # Query expansion
    
    vector_store: default
    embedder: default
    watch: true  # Real-time indexing
    incremental_indexing: true

Vector Stores

Guardrails

Deterministic and LLM-powered content protection:

Input Guardrails

guardrails:
  default:
    input:
      length:
        max_length: 50000
        action: block
      injection:
        enabled: true
        patterns: ["ignore previous", "system:"]
        action: block
        severity: critical
      sanitizer:
        trim_whitespace: true
        strip_html: true

Output Guardrails

guardrails:
  default:
    output:
      pii:
        enabled: true
        detect_email: true
        detect_phone: true
        detect_ssn: true
        detect_credit_card: true
        redact_mode: mask  # mask | remove | hash
      content:
        blocked_keywords: [profanity_list]
        blocked_patterns: ["(?i)password.*=.*"]

LLM Moderation

guardrails:
  default:
    moderation:
      enabled: true
      strategy: openai  # openai | lakera | prompt
      openai:
        model: omni-moderation-latest
        threshold: 0.8
      action: block

Authentication

JWKS/OIDC Integration

hector serve \
  --auth-jwks-url "https://auth.example.com/.well-known/jwks.json" \
  --auth-issuer "https://auth.example.com/" \
  --auth-audience "hector-api"

Simple Token Auth

hector serve --auth-secret "your-admin-secret"

Observability

Prometheus Metrics

hector serve --metrics
# Metrics available at /metrics

OpenTelemetry Tracing

hector serve --tracing-endpoint "jaeger:4317"

LLM Providers

llms:
  claude:
    provider: anthropic
    model: claude-sonnet-4
    api_key: ${ANTHROPIC_API_KEY}
    thinking:
      enabled: true
      budget_tokens: 4096
  
  gpt4:
    provider: openai
    model: gpt-4o
    api_key: ${OPENAI_API_KEY}
    
  local:
    provider: ollama
    model: llama3.2
    base_url: http://localhost:11434

Deployment

Single Binary

# Build
go build -o hector ./cmd/hector

# Run
./hector serve --config config.yaml

Docker

FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o hector ./cmd/hector

FROM alpine:latest
COPY --from=builder /app/hector /usr/local/bin/
EXPOSE 8080
CMD ["hector", "serve"]

Configuration Validation

# Validate before deploy
hector validate --config production.yaml

# JSON Schema available
curl http://localhost:8080/schema

Documentation

License

MIT (see LICENSE).