convez.ai
MCP ServerAutomaçãoAvançado
xd1lab

Boltrope — Motor de Agentes IA com Event Sourcing

xd1lab/harness-ai

Engine de agentes IA durável, multi-tenant e sem vendor lock-in

Ver no GitHub
BomPluginScore · de 0 a 100

Server MCP em Go que implementa um engine de agentes IA auto-hospedável com log de eventos durável em PostgreSQL. Oferece suporte multi-LLM (Anthropic, Gemini, OpenAI, self-hosted), execução sandboxed de ferramentas, isolamento de tenants garantido por banco de dados e auditoria completa de cada execução sem perder estado em crashes.

Instalação

$npx convez-ai xd1lab/harness-ai

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 3 meses
Versão
v0.1.0
Issues abertas
9
Contribuidores
1

Casos de uso

  • Implantar agentes IA em infraestrutura própria com conformidade regulatória
  • Construir fluxos de automação auditáveis com rastreamento permanente de execuções
  • Integrar múltiplos provedores de LLM com API única e consistente

Veredito

Solução enterprise-grade para times que precisam de propriedade total dos dados, auditoria completa e isolamento de tenants. Event sourcing em PostgreSQL é um diferencial forte para durabilidade e reproducibilidade, mas a curva de adoção é alta.

README

A tradução para o português deste README ainda está na fila.

Boltrope

The self-hostable AI-agent engine for teams that must own their data, prove tenant isolation, and audit every run.

CI Go Reference Go Report Card OpenSSF Scorecard License: Apache-2.0

English · 繁體中文

Boltrope is an AI-agent engine you run on your own infrastructure. Point it at a hosted model (Anthropic, Google, OpenAI) or one you host yourself — the same application code works against any of them. It is backend-only: no UI, no proprietary cloud, no vendor telemetry. The only things it talks to are the endpoints you point it at — your database, your model provider, your observability stack.

One idea runs through it: every run is a permanent, ordered record in a PostgreSQL database, not state held in memory. That record is what lets a run resume after a crash, be replayed or branched later, and be handed to an auditor as a complete, replayable record of what happened — and it's what keeps an agent from firing the same real-world action twice.

Why another harness? Many agent frameworks tie you to one model vendor, hold a run's state in memory (so a crash loses it), and run tools with the same access as the process that launched them. For a team that has to self-host and answer to a security review, those are three liabilities. Boltrope is built the opposite way:

  • No vendor lock-in. A single internal interface means the agent works the same against any supported model, hosted or self-hosted — switching models doesn't change your application.
  • Nothing is lost in a crash, and nothing fires twice. Every run lives in a durable database log, so a failed run resumes where it stopped, and a real-world action that already happened — an email sent, a card charged, a file written — isn't repeated.
  • Model-driven code runs in a locked box. Tools execute in a per-session sandbox with no network by default — the one place model-influenced code can run, and it can't reach out unless you allow it.

Context is treated as a finite resource — actively managed via token accounting, automatic compaction, and prompt caching.

Status: v1, backend-only (no UI yet). What works today: the agent loop, support for four model families (Anthropic, Google, OpenAI, and self-hosted/OpenAI-compatible), the durable event log, the per-session sandbox, permissions and human approvals, an MCP client, and built-in observability. See Feature overview for the full list and Roadmap for what is deliberately left out for now.


Contents


Quickstart

Bring up the full stack (PostgreSQL, schema migration, and the four services — orchestrator, model-gateway, tool-runtime, projectord) and run one task — keyless, no model API key required. Bringing up the stack needs only Docker with the Compose plugin; the harnessctl client in step 4 additionally needs Go to build/run (go run ./cmd/harnessctl …, or go build -o bin/ ./cmd/harnessctl once). The model-gateway defaults to the built-in stub provider (a deterministic, network-free provider), so a clean docker compose up runs an end-to-end task out of the box. Point it at a real model in Use a real model below.

# 1. Clone.
git clone https://github.com/xd1lab/harness-ai.git
cd harness-ai

# 2. Up — keyless. Postgres healthy -> migrate completes -> grant -> the four
#    services start. The model-gateway defaults to BOLTROPE_MODELGW_PROVIDER=stub,
#    so no .env and no API key are needed. --wait blocks until every service's
#    /readyz reports ready (each gates on its real downstream deps; see Notes).
docker compose -f deploy/docker-compose.yml up --build --wait

# 3. Confirm the whole stack is ready (each returns HTTP 200). The orchestrator's
#    HTTP edge is published on host port 8080, the gRPC edge on 9000.
curl -fsS http://localhost:8080/readyz && echo   # orchestrator: ready

# 4. Run a task. harnessctl is the gRPC client CLI; BOLTROPE_DEV_INSECURE=1 makes it
#    dial the compose edge over the shared-seed dev mTLS path (details in the note
#    below). The keyless stub replies with one deterministic text turn, so this
#    streams the assistant text and a terminal success frame.
BOLTROPE_DEV_INSECURE=1 go run ./cmd/harnessctl --endpoint localhost:9000 \
    run "Write a hello-world Go program."
# => session: 019eb1...
#    I received your task and I am working on it.
#    [result] subtype=success turns=1 cost=0.000000 USD

What the keyless run proves, and the commands beyond it. It exercises the full distributed pipeline end-to-end — client → orchestrator (mTLS + event-sourced log) → model-gateway, plus the orchestrator → tool-runtime tool advertisement and the resumable streaming relay. (Tool execution in the sandbox is covered by the tool-runtime integration suite, not this network-free demo provider — point at a real model to drive actual tool calls.) Useful flags: a session's standing permission mode is chosen at creation with --permission-mode default|acceptEdits|plan (env BOLTROPE_CTL_PERMISSION_MODE); under the default mode a real model's tool call pauses at an [approval required] prompt printing a call_id — approve it from a second terminal with harnessctl … --session <id> approve <call-id>. Reconnect to a dropped session with --session <id> --after-seq <n>; fork a trajectory with harnessctl … fork --at-seq <n>.

harnessctl over the dev edge. Under BOLTROPE_DEV_INSECURE=1 the orchestrator's gRPC edge speaks static-cert mTLS (it has no plaintext listener). Setting the same BOLTROPE_DEV_INSECURE=1 on harnessctl (as in step 4) makes it dial over the shared-seed dev CA: the CLI presents the spiffe://boltrope.local/edge identity the orchestrator's RBAC admits and pins spiffe://boltrope.local/orchestrator, completing mutual TLS against the compose edge. (Override the trust domain / pinned id with --trust-domain / --server-id, or set BOLTROPE_DEV_CA_SEED consistently across the stack.) The bare --insecure flag is plaintext-only and is for a local orchestrator started without mTLS — it cannot handshake the compose dev edge. Production uses SPIFFE/SPIRE SVIDs and OIDC at the edge.

Notes. The Compose stack lives at deploy/docker-compose.yml; it orders Postgres → migrate → grant → services with depends_on + healthchecks per docs/architecture/00-architecture.md §10. --wait returns only once every service's /readyz is green, and each service's readiness gates on its real downstream dependencies — the orchestrator on a Postgres ping and a grpc.health.v1 probe of the model-gateway and tool-runtime over the same inter-service mTLS channel it serves on, the tool-runtime additionally on docker version — so a green --wait means the stack is wired up and the inter-service mTLS actually handshakes (a shared-CA mismatch fails --wait here, not on the first turn), not merely that the processes started. It is the dev / single-tenant / trusted-code stack: it runs with BOLTROPE_DEV_INSECURE=1 (the static-cert mTLS fallback, with one shared dev-CA seed across all services) and mounts the host Docker socket into the tool-runtime (docker-out-of-docker, root-equivalent on the host — read the comments in that file). Production deployments use SPIFFE/SPIRE-issued SVIDs for inter-service mTLS, OIDC/bearer auth at the client edge, and a socket-proxied or microVM sandbox backend (see Security).

Use a real model

The stub provider proves the wiring; swap in a real model when you want real output. Provider selection is a deployment concern of the model-gateway, read from its environment. The gateway stores only the name of the env var holding the key — the value is resolved at a trusted boundary and never lands in config, the event log, or any response body. Set these in deploy/.env (git-ignored; compose reads it automatically) and re-run the up --wait above:

# deploy/.env — Anthropic Claude (swap for gemini / openai / openaicompat):
cat > deploy/.env <<'EOF'
BOLTROPE_MODELGW_PROVIDER=anthropic
BOLTROPE_MODELGW_API_KEY_ENV=ANTHROPIC_API_KEY
ANTHROPIC_API_KEY=sk-ant-...
EOF
ProviderBOLTROPE_MODELGW_PROVIDERKey env (name → in BOLTROPE_MODELGW_API_KEY_ENV)
Anthropic ClaudeanthropicANTHROPIC_API_KEY
Google GeminigeminiGEMINI_API_KEY
OpenAI (Responses API)openaiOPENAI_API_KEY
Self-hosted / OpenAI-compatible (Ollama, vLLM, LM Studio, …)openaicompatoptional — set only if the endpoint requires one; point BOLTROPE_MODELGW_OPENAI_BASE_URL at the /v1 URL

See Configuring a provider for the full matrix and per-(endpoint, model) capability resolution.

With BOLTROPE_MODELGW_PROVIDER=openaicompat pointed at a local Ollama serving gemma4:26b and a session created in acceptEdits mode, asking the agent to write a file:

$ harnessctl --endpoint localhost:9000 --session <id> \
    run "Write a hello-world Go program to hello.go, then confirm."

[tool] wrote 77 bytes to hello.go
[result] subtype=success turns=2 cost=0.000000 USD
File hello.go has been created successfully.

The model issued a real write tool call; the policy pipeline auto-approved it (acceptEdits mode), the tool executed inside the per-session Docker sandbox, and the result was fed back for a second turn — the complete gather → act → verify loop. The event log records the whole trajectory:

seq  event                  detail
1    SessionStarted
2    MessageAppended        user task
3    TurnStarted            model=gemma4:26b
4    AssistantMessage       tool_call: write(hello.go)
5    PermissionDecided      allow — "acceptEdits mode: file edit auto-approved"
6    ToolExecutionStarted   durable intent (idempotency key)
7    ToolResult             "wrote 77 bytes to hello.go"
8    MessageAppended        tool result fed back
9    TurnStarted            model=gemma4:26b
10   AssistantMessage       confirmation text
11   TurnFinished           success — usage 1670 in / 63 out tokens

Cost is $0 because the model is self-hosted; against a metered provider the same run rolls up real token usage and USD cost on the TurnFinished event.


Install

The Quickstart above runs everything from source. For a real deployment, use the released artifacts — produced by GoReleaser on every tagged release: cross-compiled, checksummed, SBOM'd, and keyless-signed with cosign (Sigstore).

Container images (multi-arch linux/amd64 + arm64, on GHCR) — one per service, the same images deploy/docker-compose.yml can pin:

docker pull ghcr.io/xd1lab/boltrope-orchestratord:latest
docker pull ghcr.io/xd1lab/boltrope-modelgwd:latest
docker pull ghcr.io/xd1lab/boltrope-toolruntimed:latest
docker pull ghcr.io/xd1lab/boltrope-projectord:latest
docker pull ghcr.io/xd1lab/boltrope-migrate:latest      # one-shot schema migration

Binaries — each GitHub release attaches two kinds of archive (cosign-signed via checksums.txt, verify before use):

  • boltrope_<version>_linux_<arch>.tar.gz — the server bundle: the four daemons + boltrope-migrate, for linux/{amd64,arm64}.
  • harnessctl_<version>_<os>_<arch> — the client CLI on its own, for linux, macOS, and Windows (.tar.gz, or .zip on Windows).

From source (Go 1.25+):

go install github.com/xd1lab/harness-ai/cmd/harnessctl@latest   # the client CLI
# daemons build with the `spire` tag for production SPIFFE/SPIRE identity:
go build -tags spire ./cmd/...

Releases are cut by a maintainer pushing a vX.Y.Z tag. The ghcr.io/xd1lab/… images and the go install path resolve once a release is published (v0.1.0 onward); before that, build from source as in the Quickstart.


REST API (SSE)

You don't need Go or gRPC to drive Boltrope: the orchestrator's HTTP listener (port 8080 in the compose stack, next to /readyz and /metrics) serves a minimal REST/JSON facade over the same server the gRPC edge uses — identical auth (the shared OIDC validator; the dev stack needs no token), identical ownership checks, identical event stream.

# 1. Create a session.
SESSION=$(curl -fsS -X POST localhost:8080/v1/sessions \
    -d '{"mode":"default"}' | jq -r .sessionId)

# 2. Run a task — the response is a live Server-Sent-Events stream.
curl -NfsS -X POST "localhost:8080/v1/sessions/$SESSION/run" \
    -d '{"text":"Write a hello-world Go program."}'
# id: 2
# event: text_delta
# data: {"seq":"2","textDelta":{"text":"I received your task..."}}
#
# event: result
# data: {"result":{"subtype":"TERMINATION_SUBTYPE_SUCCESS","numTurns":"1",...}}

# 3. Out-of-band control (approve a pending tool call, interrupt, reattach):
curl -fsS -X POST "localhost:8080/v1/sessions/$SESSION/control" \
    -d '{"action":"approve","call_id":"<call-id from the approval_request frame>"}'

Every SSE frame carries its durable event seq as the id: field, so reconnecting with the standard Last-Event-ID header (or {"after_seq": N}) resumes exactly — no duplicates, no gaps. Frame payloads are canonical protojson of the boltrope.v1.RunEvent message; in production send Authorization: Bearer <OIDC access token> and terminate TLS at your ingress.

Python, zero SDK: examples/python/run_task.py is a complete ~100-line client (pip install requests) that creates a session, streams a run, and answers approval prompts interactively.

Routes: POST /v1/sessions · GET /v1/sessions/{id} · POST /v1/sessions/{id}/run (SSE) · POST /v1/sessions/{id}/control · POST /v1/sessions/{id}/fork.


Examples

Runnable walkthroughs in examples/ — the first three run end-to-end against the keyless dev stack (no API key, no client tooling):

  • curl/ — drive a full session with nothing but curl: create, run, stream SSE, resume on Last-Event-ID.
  • durable-resume/ — inspect the per-session Postgres event log, then watch a session survive an orchestrator restart (the projection is rebuilt from the durable log, headSeq intact).
  • python/ — a ~100-line requests-only client with interactive approvals.
  • web-research/ — enable webfetch/websearch through the deny-by-default egress data path (needs a real model + an allowlisted host).

New here and weighing the options? How Boltrope compares is an honest look at Boltrope next to deepagents and hive — including where they're the better choice.


Feature overview

The capabilities behind the promises above — own your stack, isolate every tenant, act safely, audit everything — broken out in detail. Everything below is implemented in v1 unless explicitly marked roadmap.

  • Agent loop — a single-threaded gather → act → verify (ReAct-style) loop with turns, max_turns / max_budget_usd caps, and typed termination subtypes (success, error_max_turns, error_max_budget_usd, error_during_execution, error_max_structured_output_retries). Cooperative cancellation, doom-loop (stuck-loop) detection, and depth-limited sub-agents-as-tools.
  • Multi-LLM, provider-portable — one normalized Provider interface (Generate / Stream / CountTokens / Capabilities) behind the model-gateway, with adapters for Anthropic Claude, Google Gemini, OpenAI (Responses API primary, Chat Completions sub-flag), and an OpenAI-compatible adapter covering self-hosted endpoints (vLLM, Ollama, LM Studio, llama.cpp, TGI, LiteLLM). Capability flags resolve per (endpoint, model), not per provider family. The loop holds zero vendor-SDK imports — adding a provider touches only an adapter package plus a capabilities-table entry.
  • Event-sourced sessions with resume & fork — an append-only PostgreSQL log is the single source of truth. Appends are optimistic (compare expected_seq), fenced (lease epoch), and idempotent (a re-sent request_id is a no-op, not a conflict). After a crash, a run resumes from the durable log exactly where it stopped instead of starting over, replaying its recorded steps without re-doing completed work. Fork branches a session at any point in its history without touching the original — for time-travel debugging, or to freeze a real run into a test. (Because completed turns aren't re-run, a resumed run isn't re-charged for them — which only matters for long, expensive runs; for short ones the difference is negligible.)
  • Sandboxed tools — core native tools (read, edit, write, glob, grep, bash, webfetch, websearch) run inside per-session containers behind a Workspace/Runtime port. Tool inputs are JSON-Schema-validated before execution; errors surface as an Observation, never a panic. On cancellation the process group is killed at the cgroup/PID-namespace boundary. A durable dedup ledger makes mutating tools at-most-once across restarts.
  • Permissions & human-in-the-loop — a layered deny → mode → allow → tool policy pipeline with default / acceptEdits / plan / bypass modes, a taint-tracking egress gate for the lethal-trifecta risk, and approval decisions persisted as events (re-checkable on replay). A session's standing mode is set at creation: harnessctl --permission-mode default|acceptEdits|plan (env BOLTROPE_CTL_PERMISSION_MODE) applies when the CLI creates the session; bypass is operator-only and a client-supplied bypass is rejected server-side (ADR-0019).
  • MCP (client) — connect Model Context Protocol servers over stdio or HTTP with lazy schema loading; each server runs in its own confined sandbox; first-use registration requires explicit human approval and MCP tool descriptions are treated as untrusted input.
  • Hooks / middleware — PreToolUse, PostToolUse, Stop, and PreCompact hooks run as host subprocesses behind a CommandRunner port; a PreToolUse block prevents dispatch.
  • Context management — running token accounting, automatic compaction before the budget threshold, append-only tool-result clearing (stubs in the window, full content retained in the log/blob store), and tenant-scoped prompt-cache prefixes.
  • Observability — OpenTelemetry GenAI spans (invoke_agent / chat / execute_tool) with gen_ai.* attributes and trace-context propagation over gRPC; RED metrics per RPC (errors broken down by termination subtype) and USE/saturation gauges (worker-pool, live sandboxes, PG pool, blob bytes, projection lag); slog JSON logs with LogValuer secret redaction; gRPC health + HTTP /livez / /readyz with dependency-gated readiness.
  • Client API — a resumable Run server-stream (Last-Event-ID semantics) plus a unary Control RPC (approve / deny / interrupt / reattach), served over gRPC and a REST/JSON + SSE facade (Run streams as text/event-stream; identical auth and ownership checks by construction — the facade calls the same server). See REST API and examples/python/run_task.py for the zero-SDK Python path.
  • Deterministic eval harness — golden scenarios drive the real loop against a scripted fake provider and fake clock, with no network; wired into CI as a required gate.

Configuring a provider

Boltrope is provider-portable: the agent loop is identical regardless of which model serves a turn. Provider selection is a deployment concern of the model-gateway, read from the environment. The gateway stores only the name of the env var that holds the API key — the secret value is resolved at a trusted boundary and never lands in config, the event log, or any response body (per ADR-0013).

Set these on the boltrope-modelgwd service (in .env / Compose, or the process environment):

VariableMeaning
BOLTROPE_MODELGW_PROVIDERanthropic | gemini | openai | openaicompat | stub (gateway binary default: openaicompat; the Compose stack defaults to stub for the keyless path)
BOLTROPE_MODELGW_API_KEY_ENVthe name of the env var holding the upstream API key (e.g. ANTHROPIC_API_KEY); unused by stub / keyless openaicompat
BOLTROPE_MODELGW_OPENAI_BASE_URLbase URL for openai / openaicompat (default http://localhost:11434/v1, Ollama)

The stub provider is a built-in deterministic, network-free provider for local demo and CI smoke tests (it streams a scripted response and needs no key); it is the Compose default so the stack runs keyless. It is never for production.

Anthropic Claude

export ANTHROPIC_API_KEY=sk-ant-...
export BOLTROPE_MODELGW_PROVIDER=anthropic
export BOLTROPE_MODELGW_API_KEY_ENV=ANTHROPIC_API_KEY

Google Gemini (uses google.golang.org/genai)

export GEMINI_API_KEY=...
export BOLTROPE_MODELGW_PROVIDER=gemini
export BOLTROPE_MODELGW_API_KEY_ENV=GEMINI_API_KEY

OpenAI (Responses API by default)

export OPENAI_API_KEY=sk-...
export BOLTROPE_MODELGW_PROVIDER=openai
export BOLTROPE_MODELGW_API_KEY_ENV=OPENAI_API_KEY

Self-hosted / OpenAI-compatible (Ollama, vLLM, LM Studio, llama.cpp, TGI, LiteLLM) — point at the /v1 base URL; a key is optional for keyless local endpoints:

export BOLTROPE_MODELGW_PROVIDER=openaicompat
export BOLTROPE_MODELGW_OPENAI_BASE_URL=http://localhost:11434/v1   # Ollama
# export BOLTROPE_MODELGW_API_KEY_ENV=MY_GATEWAY_KEY                # if the endpoint requires one

Capability flags (streaming tool calls, parallel tool calls, vision, thinking, server-side token counting, max output tokens) are resolved per (endpoint, model) and can be overridden per endpoint. When an endpoint lacks streaming tool-call support (e.g. LM Studio), the gateway buffers and emits complete tool calls. See the Multi-LLM support matrix for per-family defaults, and ADR-0004 / ADR-0016 for the rationale.

Shared service configuration follows flags > env > file > defaults via knadh/koanf and fails fast on a missing or invalid required field. Environment variables are BOLTROPE_-prefixed, with __ as the nesting separator — e.g. BOLTROPE_POSTGRES__DSN, BOLTROPE_SERVER__GRPC_ADDR, BOLTROPE_OTLP__ENDPOINT, BOLTROPE_LOG_LEVEL, BOLTROPE_DEV_INSECURE.


Architecture

Boltrope is three long-lived services plus one projection worker, all over a single PostgreSQL instance (the durable spine). The event store is an in-process package inside the orchestrator, not a separate service — PostgreSQL already provides the data-gravity, backup, and ordering guarantees a Go shim would only add a network hop to.

Service (cmd/)Responsibility
orchestrator (boltrope-orchestratord)The brain: the agent loop, turns, permissions, hooks, context/token budget, sub-agents — and the embedded event store (append/load/fork/subscribe over pgx).
model-gateway (boltrope-modelgwd)Stateless provider abstraction: normalizes the internal message/tool model to/from each LLM SDK, streams deltas, counts tokens, resolves capabilities, centralizes provider retry + error normalization.
tool-runtime (boltrope-toolruntimed)The trust boundary for model-influenced code: tool registry (native + MCP), JSON-Schema validation, per-session sandboxes, MCP client, and the deny-by-default egress broker.
projectord (boltrope-projectord)Read-side worker (off the request path): tails the event log and runs cost-rollup and OTel-export projections with an xmin-bounded safe-advance cursor. Lag never blocks a turn.

Plus boltrope-migrate (runs DDL and exits — a release gate) and harnessctl (the client CLI/SDK). Services talk gRPC + protobuf with mTLS; the client edge is gRPC plus a minimal REST/SSE facade on the orchestrator's HTTP listener (a full REST mapping for every RPC is roadmap).

Client ──gRPC (resumable Run / Control)──> Orchestrator ──┬─ gRPC ─> Model Gateway ──> LLM APIs / self-hosted
                                            (agent loop +  │                            (Anthropic/Gemini/OpenAI)
                                             event store)  ├─ gRPC ─> Tool Runtime ──> Sandbox (per session)
                                                  │        │                            + egress broker
                                                  ▼        └──────────────────────────> External MCP servers
                                             PostgreSQL  <── projectord (cost-rollup, OTel export)
                                             (event log = single source of truth)

Read the details:

  • docs/architecture/00-architecture.md — full v1 architecture: service decomposition, the PostgreSQL event-store schema, durability & exactly-once side effects, the security model, the concurrency/cancellation model, and provider streaming across four families.
  • docs/decisions/ — the Architecture Decision Records (ADR index) recording every significant choice and its rejected alternatives.
  • ARCHITECTURE.md — a short orientation map into the above.

Security

  • Service-to-service mTLS via SPIFFE/SPIRE workload identity, with deny-by-default per-RPC verb gates. A dev-only static-cert fallback is env-gated behind BOLTROPE_DEV_INSECURE=1 and logs a loud warning — it is present in the binary but inert unless explicitly enabled; release images build with -tags spire to enable the SPIRE path.
  • Client-edge auth validates OIDC/bearer tokens (iss/aud/exp, alg=none rejected, JWKS rotation via refresh-on-miss) and verifies session ownership on every call. Production wiring is two env vars (BOLTROPE_OIDC_ISSUER / _AUDIENCE) — the orchestrator runs OIDC discovery at startup and refuses to start without a reachable, issuer-matching IdP; see the deploy walkthrough.
  • Tenant isolation at the database layer via PostgreSQL Row-Level Security (non-owner role, SET LOCAL GUC from the verified token, FORCE ROW LEVEL SECURITY).
  • Deny-by-default egress — by default an agent's sandbox has no internet access at all, so model-driven code can't quietly reach out to the network; the only way out is the webfetch/websearch tools, and even they reach only hosts an operator has explicitly allowed. In detail: the per-session sandbox runs with --network none, so in-sandbox bash and MCP-HTTP have no external network. The webfetch/websearch tools reach the outside through the egress data path (ADR-0021): a hardened in-process fetcher at the tool-runtime trust boundary, mediated per request and per redirect hop by the deny-by-default broker (BOLTROPE_TOOLRT_EGRESS_ALLOWLIST; empty ⇒ deny-all), with DNS-pinned dialing and public-address-only egress (SSRF defense). websearch queries a configured SearXNG-compatible JSON endpoint (BOLTROPE_TOOLRT_SEARCH_URL). Nothing is reachable until an operator allowlists the host — and even then the sandbox namespace itself stays severed. Provider-native/server-side tools are disabled in v1.
  • Secrets live only in model-gateway configuration (env), never in the log or any response; secret-bearing types redact via slog.LogValuer.

Deploying to Kubernetes? The production kit is the Helm chart at deploy/helm/boltrope/ — SPIRE-issued identity, OIDC edge auth, the migration-gate hook Job, and the sandboxed tool runtime, fail-closed at render time (no OIDC issuer / no SPIRE / stub provider / unacknowledged dev-insecure all refuse to render). SPIRE from zero: deploy/k8s/spire/.

Found a vulnerability? Please report it privately — see SECURITY.md. The ADR-0013 security model has the full picture.


Roadmap / Deferred

v1 is a deliberately focused, irreducible harness. The Provider, Workspace/Runtime, EventLogPort, and MCP abstractions are shaped so these slot in without re-architecture (ADR-0003):

  • MCP server mode (and A2A interoperability) — v1 ships the MCP client only.
  • microVM / gVisor / OS-native sandbox backends — v1 is containers-only behind the Workspace/Runtime port; multi-tenant execution of mutually-untrusted code is therefore out of scope for v1.
  • In-sandbox egress proxy — webfetch/websearch reach allowlisted hosts today through the egress data path (an in-process hardened fetcher mediated by the broker; ADR-0021). The sandbox itself stays --network none, so in-sandbox bash and MCP-HTTP still have no network; the forward proxy that would give the sandbox namespace a per-connection-gated path is deferred (the EgressBroker port and --network seam are shaped to slot it in without re-architecture).
  • Model routing and advanced multi-agent topologies.
  • Full REST mapping for every RPC — v1 ships the minimal facade (REST API: CreateSession / GetSession / Run over SSE / Control / Fork); a generated, annotations-based mapping of the complete proto surface is deferred.
  • Native-Ollama NDJSON adapter — the OpenAI-compatible /v1 path is used instead.
  • Semantic codebase indexing / tree-sitter repo map; LLM-based risk classifier; non-native function-calling fallback / constrained decoding.
  • Durable workspace snapshots (consistent filesystem resume after crash); virtual-filesystem context mounts; interactive workspace access.
  • SWE-bench / SWE-bench-Lite as a CI gate — the deterministic bespoke eval suite is the v1 gate; SWE-bench is a post-v1 external target.

Documentation


Contributing

Contributions are welcome. Boltrope is built spec-first and test-first — see CONTRIBUTING.md for the full workflow and docs/decisions/0006-engineering-conventions.md for the conventions CI enforces. In short:

  • Sign off every commit (git commit -s) — we use the Developer Certificate of Origin, not a CLA; PRs with unsigned commits fail the DCO check.
  • Conventional Commits — the type drives semantic versioning (fix: → patch, feat: → minor, feat!: / BREAKING CHANGE: → major).
  • Tests first. Keep go test ./... green; add -race and -tags integration for concurrency/DB changes; keep golangci-lint run clean — the depguard/forbidigo rules mechanically enforce the architecture boundaries.
  • Open a PR from a topic branch against main. All PRs need green CI (lint, unit -race, integration, build) and one maintainer approval; third-party GitHub Actions are pinned to commit SHAs — keep them pinned.

Community & support

Design partners wanted

Boltrope is young and built by a small team, so it is shaped deliberately around one kind of user: teams that self-host, need database-enforced tenant isolation and an auditable record of every run, and run agents that take real-world actions that must never fire twice. If that's you — a platform or security team standing up an internal agent service — we want your requirements driving the roadmap. Open a design-partner discussion with your use case and constraints. Honest about fit: if you're prototyping quickly or want a UI/integration catalog, other harnesses will serve you better today, and we'll say so.


Development

make tools          # install pinned dev tools (buf, protoc-gen-*, golangci-lint, migrate)
make lint           # golangci-lint run ./...
make test           # fast unit tests (no Docker/network)
make test-integration  # //go:build integration tests (needs Docker)
make gen            # regenerate protobuf stubs in gen/ (buf generate)

On Windows, run the underlying tool commands directly (each Make recipe is a single invocation — see the Makefile header).


License

Licensed under the Apache License 2.0. See NOTICE. Contributions require a Developer Certificate of Origin sign-off (git commit -s); see CONTRIBUTING.md and ADR-0002.

Ver o original no GitHub

Bom para

Relacionados