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 |
/hub/agents |
list active hub agents |
GET |
/hub/feed |
snapshot SSE feed |
WS |
/ws/hub/feed |
polling WebSocket feed |
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
workspaceis 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
connectingbut 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}/testto use current provider APIs. - Add targeted tests for the findings above.
Phase 2: Harden service lifecycle
- Replace deprecated FastAPI
on_eventstartup/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-webuiand 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-aikollabor-agentkollabor-eventskollabor-configfastapi >= 0.115uvicorn[standard] >= 0.32sse-starlette >= 2.1
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for kollabor-engine 0.11.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kollabor_engine-0.11.2.tar.gz | 62.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kollabor_engine-0.11.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 119.1 kB
Release files / kollabor_engine-0.11.2.tar.gz
| Download URL | kollabor_engine-0.11.2.tar.gz |
|---|---|
| Size | 62.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf44393409f6fbff8f44136c9c2b5ba10a2efefd5807e2bb6028268c202100d7
|
|
BLAKE2b-256 checksum How to use checksums |
59f09eabae380df412c90e37704bf64a2fce30ee2a5363ef6baa890b06814d2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / kollabor_engine-0.11.2-py3-none-any.whl
| Download URL | kollabor_engine-0.11.2-py3-none-any.whl |
|---|---|
| Size | 56.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
92d6929c5919d1275861cde41740f6f315a24ddef36b1f841b247dce3d6842ec
|
|
BLAKE2b-256 checksum How to use checksums |
9cd69ed2af02ce0442c3f34ddfb593ff0d79844dda8780adbc3d7c28c50080f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
