██╗ ██╗███████╗ ██████╗████████╗ ██████╗ ██████╗
██║ ██║██╔════╝██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗
███████║█████╗ ██║ ██║ ██║ ██║██████╔╝
██╔══██║██╔══╝ ██║ ██║ ██║ ██║██╔══██╗
██║ ██║███████╗╚██████╗ ██║ ╚██████╔╝██║ ██║
╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝
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 · Config Ref · CLI Ref · API Ref
- 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
macOS / Linux:
curl -fsSL https://gohector.dev/install.sh | sh
hector serveWindows (PowerShell):
irm https://gohector.dev/install.ps1 | iex
hector serveHomebrew:
brew install verikod/tap/hector
hector serveDocker:
docker run -p 8080:8080 ghcr.io/verikod/hector:latest serveOpen 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 serveOpen 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 is the web UI for designing, testing, and managing agents. It's embedded in the Hector binary — just run hector serve and open http://localhost:8080/.
- 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
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:5173See the Studio Guide for details.
All runtime state persists to SQL (SQLite or PostgreSQL):
| Component | Persistence |
|---|---|
| Sessions | Event-sourced state with scoped variables (app/user/temp) |
| Tasks | Durable queue with retry, exponential backoff, and recovery |
| Checkpoints | Incremental progress snapshots for long-running operations |
| App Configs | Hot-reloadable YAML with database sync |
# SQLite (default)
hector serve --database sqlite://.hector/hector.db
# PostgreSQL
hector serve --database postgres://user:pass@localhost/hectorA 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
Manage apps, sessions, and queue via REST endpoints. Requires --auth-secret for authentication.
hector serve --auth-secret "admin-secret"| Endpoint | Method | Description |
|---|---|---|
/admin/apps |
GET | List all apps |
/admin/apps |
POST | Create new app (returns JWT) |
/admin/apps/{id} |
GET | Get app details |
/admin/apps/{id} |
PUT | Update app config |
/admin/apps/{id} |
DELETE | Delete app and all resources |
/admin/apps/{id}/token |
POST | Regenerate app JWT |
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"
}| Endpoint | Method | Description |
|---|---|---|
/admin/sessions |
GET | List sessions (paginated) |
/admin/sessions/{id} |
GET | Get session with events |
/admin/sessions/{id} |
DELETE | Delete session |
| Endpoint | Method | Description |
|---|---|---|
/admin/queue/stats |
GET | Queue statistics |
/admin/queue/dlq |
GET | List dead-letter queue items |
/admin/queue/dlq/{id}/requeue |
POST | Requeue failed task |
# Public key for JWT verification
curl http://localhost:8080/admin/jwks| Type | Description |
|---|---|
llm |
Standard LLM-backed agent (default) |
sequential |
Runs sub-agents in order |
parallel |
Runs sub-agents concurrently |
loop |
Iterates until condition met |
conditional |
Routes based on evaluation |
remote |
Proxies to external A2A server |
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...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?}| Syntax | Resolution |
|---|---|
{variable} |
Session state |
{app:variable} |
App-scoped state |
{user:variable} |
User-scoped state |
{temp:variable} |
Temporary state |
{artifact.file} |
Artifact content |
{variable?} |
Optional (empty if missing) |
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}}"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 | callbackA2A-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: 30sNative 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| Tool | Description |
|---|---|
filetool |
File system operations with sandboxing |
webtool |
HTTP requests, web scraping |
commandtool |
Shell execution with allowlists |
memorytool |
Cross-session memory persistence |
searchtool |
RAG document search |
todotool |
Task/checklist management |
approvaltool |
Human-in-the-loop approvals |
agenttool |
Agent-as-callable-tool |
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?"Enterprise-grade retrieval-augmented generation:
| Source | Description |
|---|---|
directory |
File system with glob patterns |
sql |
Database tables with incremental sync |
api |
REST endpoints |
blob |
Cloud storage (S3, GCS, Azure) |
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| Provider | Type |
|---|---|
| chromem | Embedded (default) |
| Qdrant | External |
| Pinecone | Cloud |
| Weaviate | External |
| Milvus | External |
Deterministic and LLM-powered content protection:
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: trueguardrails:
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.*=.*"]guardrails:
default:
moderation:
enabled: true
strategy: openai # openai | lakera | prompt
openai:
model: omni-moderation-latest
threshold: 0.8
action: blockhector serve \
--auth-jwks-url "https://auth.example.com/.well-known/jwks.json" \
--auth-issuer "https://auth.example.com/" \
--auth-audience "hector-api"hector serve --auth-secret "your-admin-secret"hector serve --metrics
# Metrics available at /metricshector serve --tracing-endpoint "jaeger:4317"| Provider | Features |
|---|---|
| Anthropic | Claude 4, streaming, thinking blocks, multimodal |
| OpenAI | GPT-4o, structured output, reasoning |
| Gemini | Multimodal (audio, image, video) |
| Ollama | Local inference, any open model |
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# Build
go build -o hector ./cmd/hector
# Run
./hector serve --config config.yamlFROM 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"]# Validate before deploy
hector validate --config production.yaml
# JSON Schema available
curl http://localhost:8080/schema| Resource | Description |
|---|---|
| Quick Start | Get running in 5 minutes |
| Hector Studio | Web UI for agent development |
| Configuration Reference | Complete YAML schema |
| CLI Reference | All commands and flags |
| API Reference | HTTP API & Admin endpoints |
| Go API Reference | Programmatic API |
| Architecture | System design & internals |
MIT (see LICENSE).
