kollabor-engine

kollabor-engine is the local HTTP/SSE runtime for Kollabor.

It wraps the same core AI, tool, permission, profile, MCP, and hub pieces used by the terminal app, but exposes them through a FastAPI service. The intended use is a local companion daemon for kollabor-webui, browser-based control surfaces, and other trusted local clients.

This package is not yet a production multi-user service. It currently relies on in-memory sessions and process-global runtime state, so treat it as a per-user local service bound to 127.0.0.1.

Current Role

• Headless HTTP API for creating chat sessions and sending turns.
• SSE streaming for model tokens, thinking content, tool events, permission prompts, and turn completion metadata.
• Local profile management over the existing Kollabor profile store.
• Session-owned permission manager and MCP integration.
• Hub mesh read/control endpoints for active local agents.
• Web UI backend for kollabor-webui.

Architecture

The engine is a thin service layer over other workspace packages:

Main engine modules:

Usage

To run this alongside kollabor-webui in one step, use kollab --web-ui from the repo root instead (see packages/kollabor-webui/README.md).

Start the local service on its own:

python -m kollabor_engine serve --host 127.0.0.1 --port 7433

On startup, the service writes a bearer token to:

~/.kollab/engine.token

Use that token for protected endpoints:

TOKEN="$(cat ~/.kollab/engine.token)"

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:7433/sessions

Programmatic app creation:

from kollabor_engine import create_app

app = create_app()

API Surface

Health and metadata endpoints:

Session and message endpoints:

Permissions:

Profiles, MCP, and hub routes:

Known Gaps

These are current implementation gaps to address before treating the engine as a reliable service boundary:

• Profile read/update responses must redact API keys and other secret fields.
• Session workspace is stored but not yet enforced for terminal and file tools.
• Provider instances are singleton per provider type, which can leak model, base URL, headers, or credentials across sessions.
• The session MCP connect endpoint currently reports connecting but does not start a connection.
• Anthropic profile testing imports a missing legacy APIService.
• Shutdown cleans up sessions, but provider-registry and background watcher lifecycle still need a first-class lifespan model.

Roadmap

Phase 1: Make the local daemon trustworthy

• Redact profile secrets from all profile API responses.
• Enforce session workspace for shell, file, and MCP tool execution.
• Replace provider-type singletons with config-scoped or session-scoped provider instances.
• Implement real session MCP connect behavior and add tests that prove tools are registered after connection.
• Fix /profiles/{name}/test to use current provider APIs.
• Add targeted tests for the findings above.

Phase 2: Harden service lifecycle

• Replace deprecated FastAPI on_event startup/shutdown hooks with lifespan management.
• Move the module-level session registry behind an explicit service object.
• Add provider-registry shutdown and WebSocket watcher cleanup to app shutdown.
• Add concurrency guards around session mutation, message turns, permission resolution, and history/system-prompt changes.
• Normalize error payloads and request/response schemas.

Phase 3: Clarify service boundaries

• Decide whether engine owns tool execution directly or wraps the existing CLI runtime as a client-facing API.
• Add a project/session namespace model so multiple workspaces can run without cwd or hub-presence ambiguity.
• Define which endpoints are local-only, trusted-client-only, or safe for broader exposure.
• Document compatibility expectations for kollabor-webui and external clients.

Phase 4: Productize the web/hub path

• Finish live hub event streaming beyond snapshot polling.
• Add richer permission scopes and UI feedback over SSE.
• Persist recoverable session metadata where useful.
• Add smoke tests that start engine + web UI against a temporary config home.

Development

Run package tests against the local source tree:

PYTHONPATH=packages/kollabor-engine/src:packages/kollabor-ai/src:packages/kollabor-agent/src:packages/kollabor-events/src:packages/kollabor-config/src:packages/kollabor-rpc/src:packages/kollabor-tui/src:packages/kollabor-plugins/src \
  python -m pytest packages/kollabor-engine/tests -q

Without the PYTHONPATH override, this checkout may import an installed kollabor_engine from site-packages instead of the local package.

Dependencies

• kollabor-ai
• kollabor-agent
• kollabor-events
• kollabor-config
• fastapi >= 0.115
• uvicorn[standard] >= 0.32
• sse-starlette >= 2.1

License

MIT