Backend

ResolveKit Backend is a multi-service runtime for agent orchestration, tool routing, knowledge retrieval, and operational control.

Architecture

Primary services in resolvekit-backend:

• agent (FastAPI): SDK session lifecycle, event stream, tool result ingestion, function registration.
• knowledge_bases (FastAPI): KB creation, source ingestion (URL/upload), embedding/search, usage summaries.
• dashboard (Next.js): dashboard UI + /v1/* control-plane API route handlers.
• Data plane: PostgreSQL + Redis.

Quick Start

Prerequisites

• Python 3.13.x
• Docker + Docker Compose
• LLM provider credentials (for configured profile)

Run with Docker Compose

cd resolvekit-backend
cp .env.example .env
docker compose up -d

Default local ports:

• Agent: 8000
• KB Service: 8100
• Dashboard: 3000
• Dashboard API boundary: 3002
• Postgres: 15432 (agent), 15433 (knowledge_bases)
• Redis: 16379

Run services directly

# Agent
uv run python -m agent.main

# KB service
uv run python -m knowledge_bases.main

# Dashboard
cd dashboard && npm run dev

Configuration

Agent (IAA_*)

High-impact variables:

• IAA_DATABASE_URL
• IAA_REDIS_URL
• IAA_CORS_ORIGINS
• IAA_JWT_SECRET
• IAA_ENCRYPTION_KEY
• IAA_MINIMUM_SDK_VERSION
• IAA_SUPPORTED_SDK_MAJOR_VERSIONS
• IAA_CHAT_CAPABILITY_SECRET
• IAA_CHAT_CAPABILITY_TTL_SECONDS
• IAA_SDK_CLIENT_TOKEN_SECRET
• IAA_SDK_CLIENT_TOKEN_TTL_SECONDS
• IAA_KNOWLEDGE_BASES_BASE_URL
• IAA_KNOWLEDGE_BASES_AUDIENCE
• IAA_KNOWLEDGE_BASES_SIGNING_KEY

Knowledge Bases (KBS_*)

• KBS_DATABASE_URL
• KBS_SERVICE_JWT_SIGNING_KEY
• KBS_SERVICE_JWT_AUDIENCE
• KBS_ENCRYPTION_KEY
• KBS_CRAWL_*
• KBS_UPLOAD_*
• KBS_WORKER_ENABLED

Dashboard / Control Plane

• NEXT_PUBLIC_API_BASE_URL
• RESOLVEKIT_SERVER_AGENT_BASE_URL
• DATABASE_URL (Prisma)
• IAA_JWT_SECRET, IAA_ENCRYPTION_KEY
• IAA_KNOWLEDGE_BASES_*

Knowledge Bases

KB service endpoints live under /internal/* and are called by control-plane server routes.

Functional domains:

• KB lifecycle: create/list/get/update/delete
• Source ingestion: URL crawl, upload, upload-file, recrawl, source deletion
• Search: single KB and multi-KB search
• Embeddings: org embedding profile CRUD + impact checks
• Jobs/documents: ingestion job listing + document listing/deletion
• Usage: aggregate usage summaries

Dashboard

Dashboard repository role:

• UI (dash) for operators
• API boundary (api) using Next route handlers under /v1/*

Major control-plane surfaces include:

• Apps, app config, API keys, functions, sessions, playbooks
• Knowledge bases and document/source operations
• Organization members, invitations, onboarding, LLM profiles, embedding profiles
• Spend and audit endpoints

Security and Runtime Notes

• Production startup validates critical secrets when debug is off.
• Session runtime uses bearer auth plus session capability token.
• Event transport is SSE with cursor replay support.
• Redis is used for runtime continuity and tool-result coordination.