{"id":34667541,"url":"https://github.com/verikod/hector","last_synced_at":"2026-04-19T02:18:15.009Z","repository":{"id":315402615,"uuid":"1058641128","full_name":"verikod/hector","owner":"verikod","description":"A2A-Native AI Agent Platform written in Go","archived":false,"fork":false,"pushed_at":"2026-04-15T00:41:56.000Z","size":965,"stargazers_count":53,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T02:35:24.150Z","etag":null,"topics":["a2a-protocol","ai","ai-agent-tools","ai-agents","ai-agents-framework","declarative","golang"],"latest_commit_sha":null,"homepage":"https://gohector.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verikod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-17T11:03:12.000Z","updated_at":"2026-04-15T00:42:00.000Z","dependencies_parsed_at":"2025-09-18T12:39:28.896Z","dependency_job_id":"123e9c63-15d5-4c27-983f-ae6059823cf4","html_url":"https://github.com/verikod/hector","commit_stats":null,"previous_names":["kadirpekel/hector"],"tags_count":126,"template":false,"template_full_name":null,"purl":"pkg:github/verikod/hector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verikod%2Fhector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verikod%2Fhector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verikod%2Fhector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verikod%2Fhector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verikod","download_url":"https://codeload.github.com/verikod/hector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verikod%2Fhector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31991755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-protocol","ai","ai-agent-tools","ai-agents","ai-agents-framework","declarative","golang"],"created_at":"2025-12-24T19:21:34.361Z","updated_at":"2026-04-19T02:18:15.002Z","avatar_url":"https://github.com/verikod.png","language":"Go","funding_links":[],"categories":["⚙️ Implementations \u0026 Libraries"],"sub_categories":[],"readme":"```\n██╗  ██╗███████╗ ██████╗████████╗ ██████╗ ██████╗ \n██║  ██║██╔════╝██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗\n███████║█████╗  ██║        ██║   ██║   ██║██████╔╝\n██╔══██║██╔══╝  ██║        ██║   ██║   ██║██╔══██╗\n██║  ██║███████╗╚██████╗   ██║   ╚██████╔╝██║  ██║\n╚═╝  ╚═╝╚══════╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝\n```\n\n[![Go Version](https://img.shields.io/badge/go-1.24+-00ADD8.svg)](https://golang.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![A2A Protocol](https://img.shields.io/badge/A2A%20v0.3.0-100%25%20compliant-brightgreen.svg)](https://a2a-protocol.org/latest/community/#a2a-integrations)\n[![Documentation](https://img.shields.io/badge/docs-gohector.dev-blue.svg)](https://gohector.dev)\n[![Go Report Card](https://goreportcard.com/badge/github.com/verikod/hector)](https://goreportcard.com/report/github.com/verikod/hector)\n\n**Your agents. Your infrastructure. Your rules.**\n\nHector 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.\n\n![Hector Studio](docs/assets/ss.png)\n\n**[Documentation](https://gohector.dev)** · **[Config Ref](https://gohector.dev/reference/configuration/)** · **[CLI Ref](https://gohector.dev/reference/cli/)** · **[API Ref](https://gohector.dev/reference/api/)**\n\n---\n\n## Why Hector?\n\n- **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\n- **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\n- **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\n- **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\n- **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\n- **Enterprise Security \u0026 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\n\n---\n\n## Quick Start\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://gohector.dev/install.sh | sh\nhector serve\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://gohector.dev/install.ps1 | iex\nhector serve\n```\n\n**Homebrew:**\n\n```bash\nbrew install verikod/tap/hector\nhector serve\n```\n\n**Docker:**\n\n```bash\ndocker run -p 8080:8080 ghcr.io/verikod/hector:latest serve\n```\n\nOpen **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\n```\n\n**Homebrew:**\n\n```bash\nbrew install verikod/tap/hector\nhector serve\n```\n\n**Docker:**\n\n```bash\ndocker run -p 8080:8080 ghcr.io/verikod/hector:latest serve\n```\n\nOpen **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.\n\n---\n\n## Hector Studio\n\nHector 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/**.\n\n- **Visual Flow Builder**: Drag-and-drop canvas with bi-directional YAML sync\n- **Integrated Chat**: Streaming responses with tool-call trace view\n- **Resource Management**: Configure LLMs, tools, and guardrails without editing YAML\n\nStudio is also embedded in release builds and served at `/`. For development builds:\n\n```bash\n# Option 1: Build a single binary with UI embedded (requires Node.js)\nmake build-release\n\n# Option 2: Run Studio dev server (hot-reload for UI development)\ncd studio \u0026\u0026 npm run dev   # → http://localhost:5173\n```\n\nSee the [Studio Guide](https://gohector.dev/guides/studio/) for details.\n\n---\n\n## Core Architecture\n\n### SQL-Backed Foundation\n\nAll runtime state persists to SQL (SQLite or PostgreSQL):\n\n| Component | Persistence |\n|-----------|-------------|\n| **Sessions** | Event-sourced state with scoped variables (app/user/temp) |\n| **Tasks** | Durable queue with retry, exponential backoff, and recovery |\n| **Checkpoints** | Incremental progress snapshots for long-running operations |\n| **App Configs** | Hot-reloadable YAML with database sync |\n\n```bash\n# SQLite (default)\nhector serve --database sqlite://.hector/hector.db\n\n# PostgreSQL\nhector serve --database postgres://user:pass@localhost/hector\n```\n\n### Multi-Tenant Architecture\n\nA single Hector deployment can host multiple isolated apps via the **Admin API** (not file-based configs). Each app has:\n\n- Isolated agent configurations\n- Separate session and state storage\n- Independent vector store collections\n- Per-app JWT authentication\n\n---\n\n## Admin API\n\nManage apps, sessions, and queue via REST endpoints. Requires `--auth-secret` for authentication.\n\n```bash\nhector serve --auth-secret \"admin-secret\"\n```\n\n### App Management\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/admin/apps` | GET | List all apps |\n| `/admin/apps` | POST | Create new app (returns JWT) |\n| `/admin/apps/{id}` | GET | Get app details |\n| `/admin/apps/{id}` | PUT | Update app config |\n| `/admin/apps/{id}` | DELETE | Delete app and all resources |\n| `/admin/apps/{id}/token` | POST | Regenerate app JWT |\n\n**Create App:**\n```bash\ncurl -X POST http://localhost:8080/admin/apps \\\n  -H \"Authorization: Bearer admin-secret\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"customer-support\", \"config_json\": \"{...}\"}'\n\n# Response includes JWT for app authentication\n{\n  \"app\": {\"id\": \"abc123\", \"name\": \"customer-support\"},\n  \"access_token\": \"eyJhbGc...\",\n  \"token_type\": \"bearer\"\n}\n```\n\n### Session Management\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/admin/sessions` | GET | List sessions (paginated) |\n| `/admin/sessions/{id}` | GET | Get session with events |\n| `/admin/sessions/{id}` | DELETE | Delete session |\n\n### Queue Management\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/admin/queue/stats` | GET | Queue statistics |\n| `/admin/queue/dlq` | GET | List dead-letter queue items |\n| `/admin/queue/dlq/{id}/requeue` | POST | Requeue failed task |\n\n### JWKS Endpoint\n\n```bash\n# Public key for JWT verification\ncurl http://localhost:8080/admin/jwks\n```\n\n---\n\n## Agent Capabilities\n\n### Agent Types\n\n| Type | Description |\n|------|-------------|\n| `llm` | Standard LLM-backed agent (default) |\n| `sequential` | Runs sub-agents in order |\n| `parallel` | Runs sub-agents concurrently |\n| `loop` | Iterates until condition met |\n| `conditional` | Routes based on evaluation |\n| `remote` | Proxies to external A2A server |\n\n### Multi-Agent Patterns\n\n```yaml\nagents:\n  # Agent-as-tool: Call other agents like functions\n  orchestrator:\n    llm: default\n    agent_tools: [researcher, writer]\n\n  # Sub-agent delegation: Transfer control\n  manager:\n    llm: default\n    sub_agents: [analyst, reporter]\n\n  # Conditional routing\n  router:\n    type: conditional\n    condition_agent: classifier\n    condition_field: category\n    on_true_agent: sales\n    on_false_response: Redirecting to support...\n```\n\n### Instruction Templating\n\nDynamic instruction resolution from session state:\n\n```yaml\nagents:\n  assistant:\n    instruction: |\n      Hello {user:name}, you're working on {app:project}.\n      \n      Context: {artifact.context.md}\n      \n      Previous summary: {temp:last_summary?}\n```\n\n| Syntax | Resolution |\n|--------|------------|\n| `{variable}` | Session state |\n| `{app:variable}` | App-scoped state |\n| `{user:variable}` | User-scoped state |\n| `{temp:variable}` | Temporary state |\n| `{artifact.file}` | Artifact content |\n| `{variable?}` | Optional (empty if missing) |\n\n---\n\n## Automation \u0026 Integration\n\n### Scheduled Triggers\n\nRun agents on cron schedules with timezone support:\n\n```yaml\nagents:\n  daily_report:\n    llm: default\n    instruction: Generate the daily summary report.\n    trigger:\n      type: schedule\n      cron: \"0 9 * * *\"  # Daily at 9am\n      timezone: America/New_York\n      input: \"Generate report for {{.Date}}\"\n```\n\n### Webhook Triggers\n\nInvoke agents via HTTP with payload transformation:\n\n```yaml\nagents:\n  github_handler:\n    llm: default\n    trigger:\n      type: webhook\n      path: /webhooks/github\n      methods: [POST]\n      secret: ${WEBHOOK_SECRET}\n      signature_header: X-Hub-Signature-256\n      webhook_input:\n        template: \"PR #{{.number}} by {{.user.login}}: {{.title}}\"\n        session_id: \"pr-{{.number}}\"\n        extract_fields:\n          - path: pull_request.title\n            as: title\n      response:\n        mode: async  # sync | async | callback\n```\n\n### Outbound Notifications\n\nA2A-compliant push notifications on agent events:\n\n```yaml\nagents:\n  processor:\n    llm: default\n    notifications:\n      - id: slack-notify\n        url: https://hooks.slack.com/services/xxx\n        events: [task_completed, task_failed]\n        headers:\n          Content-Type: application/json\n        payload:\n          template: |\n            {\"text\": \"Agent {{.AgentName}}: {{.Status}}\"}\n        retry:\n          max_attempts: 3\n          initial_delay: 1s\n          max_delay: 30s\n```\n\n---\n\n## Tool Ecosystem\n\n### MCP Protocol Support\n\nNative Model Context Protocol with all transports:\n\n```yaml\ntools:\n  filesystem:\n    type: mcp\n    transport: stdio\n    command: npx\n    args: [-y, \"@modelcontextprotocol/server-filesystem\", \"./data\"]\n    filter: [read_file, write_file]  # Limit exposed tools\n\n  remote_mcp:\n    type: mcp\n    transport: sse\n    url: http://localhost:8000/mcp\n```\n\n### Built-in Tools\n\n| Tool | Description |\n|------|-------------|\n| `filetool` | File system operations with sandboxing |\n| `webtool` | HTTP requests, web scraping |\n| `commandtool` | Shell execution with allowlists |\n| `memorytool` | Cross-session memory persistence |\n| `searchtool` | RAG document search |\n| `todotool` | Task/checklist management |\n| `approvaltool` | Human-in-the-loop approvals |\n| `agenttool` | Agent-as-callable-tool |\n\n### Command Tool with Security\n\n```yaml\ntools:\n  shell:\n    type: command\n    allowed_commands: [ls, cat, grep, find]\n    denied_commands: [rm, sudo]\n    working_directory: /app/workspace\n    max_execution_time: 30s\n    require_approval: true\n    approval_prompt: \"Allow command execution?\"\n```\n\n---\n\n## RAG Pipeline\n\nEnterprise-grade retrieval-augmented generation:\n\n### Document Sources\n\n| Source | Description |\n|--------|-------------|\n| `directory` | File system with glob patterns |\n| `sql` | Database tables with incremental sync |\n| `api` | REST endpoints |\n| `blob` | Cloud storage (S3, GCS, Azure) |\n\n### Advanced Retrieval\n\n```yaml\ndocument_stores:\n  knowledge:\n    source:\n      type: directory\n      include: [\"**/*.md\", \"**/*.pdf\"]\n      exclude: [\"**/node_modules/**\"]\n    \n    chunking:\n      strategy: semantic\n      size: 1000\n      overlap: 200\n    \n    search:\n      top_k: 10\n      threshold: 0.7\n      enable_hyde: true      # Hypothetical document embeddings\n      enable_rerank: true    # LLM reranking\n      enable_multi_query: true  # Query expansion\n    \n    vector_store: default\n    embedder: default\n    watch: true  # Real-time indexing\n    incremental_indexing: true\n```\n\n### Vector Stores\n\n| Provider | Type |\n|----------|------|\n| chromem | Embedded (default) |\n| Qdrant | External |\n| Pinecone | Cloud |\n| Weaviate | External |\n| Milvus | External |\n\n---\n\n## Guardrails\n\nDeterministic and LLM-powered content protection:\n\n### Input Guardrails\n\n```yaml\nguardrails:\n  default:\n    input:\n      length:\n        max_length: 50000\n        action: block\n      injection:\n        enabled: true\n        patterns: [\"ignore previous\", \"system:\"]\n        action: block\n        severity: critical\n      sanitizer:\n        trim_whitespace: true\n        strip_html: true\n```\n\n### Output Guardrails\n\n```yaml\nguardrails:\n  default:\n    output:\n      pii:\n        enabled: true\n        detect_email: true\n        detect_phone: true\n        detect_ssn: true\n        detect_credit_card: true\n        redact_mode: mask  # mask | remove | hash\n      content:\n        blocked_keywords: [profanity_list]\n        blocked_patterns: [\"(?i)password.*=.*\"]\n```\n\n### LLM Moderation\n\n```yaml\nguardrails:\n  default:\n    moderation:\n      enabled: true\n      strategy: openai  # openai | lakera | prompt\n      openai:\n        model: omni-moderation-latest\n        threshold: 0.8\n      action: block\n```\n\n---\n\n## Authentication\n\n### JWKS/OIDC Integration\n\n```bash\nhector serve \\\n  --auth-jwks-url \"https://auth.example.com/.well-known/jwks.json\" \\\n  --auth-issuer \"https://auth.example.com/\" \\\n  --auth-audience \"hector-api\"\n```\n\n### Simple Token Auth\n\n```bash\nhector serve --auth-secret \"your-admin-secret\"\n```\n\n---\n\n## Observability\n\n### Prometheus Metrics\n\n```bash\nhector serve --metrics\n# Metrics available at /metrics\n```\n\n### OpenTelemetry Tracing\n\n```bash\nhector serve --tracing-endpoint \"jaeger:4317\"\n```\n\n---\n\n## LLM Providers\n\n| Provider | Features |\n|----------|----------|\n| **Anthropic** | Claude 4, streaming, thinking blocks, multimodal |\n| **OpenAI** | GPT-4o, structured output, reasoning |\n| **Gemini** | Multimodal (audio, image, video) |\n| **Ollama** | Local inference, any open model |\n\n```yaml\nllms:\n  claude:\n    provider: anthropic\n    model: claude-sonnet-4\n    api_key: ${ANTHROPIC_API_KEY}\n    thinking:\n      enabled: true\n      budget_tokens: 4096\n  \n  gpt4:\n    provider: openai\n    model: gpt-4o\n    api_key: ${OPENAI_API_KEY}\n    \n  local:\n    provider: ollama\n    model: llama3.2\n    base_url: http://localhost:11434\n```\n\n---\n\n## Deployment\n\n### Single Binary\n\n```bash\n# Build\ngo build -o hector ./cmd/hector\n\n# Run\n./hector serve --config config.yaml\n```\n\n### Docker\n\n```dockerfile\nFROM golang:1.24-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o hector ./cmd/hector\n\nFROM alpine:latest\nCOPY --from=builder /app/hector /usr/local/bin/\nEXPOSE 8080\nCMD [\"hector\", \"serve\"]\n```\n\n### Configuration Validation\n\n```bash\n# Validate before deploy\nhector validate --config production.yaml\n\n# JSON Schema available\ncurl http://localhost:8080/schema\n```\n\n---\n\n## Documentation\n\n| Resource | Description |\n|----------|-------------|\n| [Quick Start](https://gohector.dev/getting-started/quick-start/) | Get running in 5 minutes |\n| [Hector Studio](https://gohector.dev/guides/studio/) | Web UI for agent development |\n| [Configuration Reference](https://gohector.dev/reference/configuration/) | Complete YAML schema |\n| [CLI Reference](https://gohector.dev/reference/cli/) | All commands and flags |\n| [API Reference](https://gohector.dev/reference/api/) | HTTP API \u0026 Admin endpoints |\n| [Go API Reference](https://gohector.dev/reference/go-api/) | Programmatic API |\n| [Architecture](https://gohector.dev/reference/architecture/) | System design \u0026 internals |\n\n---\n\n## License\n\nMIT (see [LICENSE](LICENSE)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverikod%2Fhector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverikod%2Fhector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverikod%2Fhector/lists"}