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:

Package	Engine Use
`kollabor-ai`	profiles, provider calls, streaming, tool-call parsing
`kollabor-agent`	tool execution, MCP connections, permissions
`kollabor-events`	per-session event bus and permission hooks
`kollabor-config`	profile/config compatibility
`kollabor-rpc`	hub-adjacent RPC foundations

Main engine modules:

Module	Responsibility
`server.py`	FastAPI app, auth middleware, global session registry
`session.py`	`EngineSession`, per-session AI/tool/permission state
`turn_runner.py`	multi-step LLM turn loop and SSE event production
`sse.py`	event payload builders
`routes/sessions.py`	session lifecycle, history, system prompt, session MCP
`routes/messages.py`	message stream and cancellation
`routes/permissions.py`	permission responses and approval mode
`routes/profiles.py`	profile CRUD and connectivity checks
`routes/mcp.py`	global MCP server config CRUD
`routes/hub.py` / `routes/hub_ws.py`	hub mesh REST and WebSocket views

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:

Method	Path	Notes
`GET`	`/health`	unauthenticated liveness check
`GET`	`/version`	package and Python versions
`GET`	`/status`	session count, providers, MCP status
`GET`	`/ready`	profile/API credential readiness

Session and message endpoints:

Method	Path	Notes
`POST`	`/sessions`	create a session
`GET`	`/sessions`	list sessions
`GET`	`/sessions/{session_id}`	inspect one session
`DELETE`	`/sessions/{session_id}`	shut down and remove a session
`GET`	`/sessions/{session_id}/history`	read conversation history
`DELETE`	`/sessions/{session_id}/history`	clear history, preserving system prompt
`POST`	`/sessions/{session_id}/message`	send one turn; returns SSE
`POST`	`/sessions/{session_id}/cancel`	cancel active turn

Permissions:

Method	Path	Notes
`GET`	`/sessions/{session_id}/permissions`	current approval mode and pending tools
`POST`	`/sessions/{session_id}/permission`	approve or deny a pending tool
`POST`	`/sessions/{session_id}/permissions/mode`	set approval mode

Profiles, MCP, and hub routes:

Method	Path	Notes
`GET`	`/profiles`	list configured profiles
`POST`	`/profiles`	create profile
`GET`	`/profiles/{name}`	inspect profile
`PUT`	`/profiles/{name}`	update or rename profile
`DELETE`	`/profiles/{name}`	delete profile
`POST`	`/profiles/{name}/test`	test provider connectivity
`GET`	`/mcp/servers`	list global MCP server config
`POST`	`/mcp/servers`	add global MCP server config
`PUT`	`/mcp/servers/{server_name}`	replace server config
`DELETE`	`/mcp/servers/{server_name}`	remove server config
`GET`	`/sessions/{session_id}/mcp`	session MCP connection status
`POST`	`/sessions/{session_id}/mcp/{server_name}/connect`	intended session connect endpoint
`POST`	`/sessions/{session_id}/mcp/{server_name}/disconnect`	disconnect session server
`GET`	`/agents`	gem identity pool: name, caste, `color` as `[r, g, b]`, live state and task; a gem listed alive for the first time is born (gets its random look)
`GET`/`PUT`	`/agents/appearance`	gem looks: `season`, `born.<name>` (`face`, `hat`: rolled once, the first time `GET /agents` lists the gem alive; PUT never changes them) and the user's `gems.<name>` (`face`, `hat`, `color`); PUT normalizes (unknown keys dropped, at most 256 gems) and writes `~/.kollab/hub/appearance.json` atomically
`GET`	`/hub/agents`	list active hub agents
`GET`	`/hub/feed`	snapshot SSE feed
`WS`	`/ws/hub/feed?token=<engine token>`	polling WebSocket feed (closed with 1008 without a valid token): `hub_snapshot` on connect, then `agent_joined`, `agent_left` and `agent_state_changed` (fires on a state or `current_task` change; carries `identity`, `state`, `old_state`, `current_task`)

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

Metadata

Release files for kollabor-engine 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kollabor-engine 0.13.0
File	Size	Uploaded
kollabor_engine-0.13.0.tar.gz	83.5 kB	Oct 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for kollabor-engine 0.13.0
File	Interpreter	ABI	Platform	Reset
kollabor_engine-0.13.0-py3-none-any.whl 66.1 kB Oct 8, 2026	Python 3	none	any	Details

Total release size: 149.6 kB

Release files / kollabor_engine-0.13.0.tar.gz

Download URL	kollabor_engine-0.13.0.tar.gz
Size	83.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`d22ec3e1366cb1643f89a28c88a01cd75c05d7c9277feec85487b187ec018899`
BLAKE2b-256 checksum How to use checksums	`3e7343b43b83034a0b9bae421a8715e6657bb095c9a442c1614628ff902e2000`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / kollabor_engine-0.13.0-py3-none-any.whl

Download URL	kollabor_engine-0.13.0-py3-none-any.whl
Size	66.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ba2cdba0545d631cf8dd3152dac42269b0643482edeb96a1d3c4a18f5578e365`
BLAKE2b-256 checksum How to use checksums	`d372ac3c8285b0005a9f0e5528a4aff0f4d13b0991ba43e23afd3aa25e10cffa`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`