Kairos Control Plane

A local-first AI agent workspace for building, investigating, and operating projects with visible safety controls.

Kairos combines a local web control plane, configurable AI providers, skills-aware planning, MCP-connected tools, protected workspace actions, and Docker-isolated command execution. It is designed to keep control with the operator: secrets remain local, provider settings are editable, sensitive actions require approval, and the browser interface is bound to loopback by default.

Release capability	What it provides
Local control plane	A polished browser interface at http://127.0.0.1:3210 for chat, provider setup, MCP management, crawling, and data analysis.
Flexible AI routing	Local Ollama, direct Ollama Cloud, Gemini, OpenAI, Anthropic, OpenRouter, Groq, Together AI, Mistral, DeepSeek, Kimi, LM Studio, custom OpenAI-compatible endpoints, and a Codex bridge.
Agent context	The agent selects relevant local skills, retained conversation history, goal lessons, and project-index context before it plans work.
MCP-ready operations	Register, inspect, test, and invoke approved MCP tools through stdio or HTTP transports. Every agent MCP invocation is visibly reviewed.
Practical local tools	Public-page crawler ZIP exports, private local CSV/JSON profiling, workspace operations, guarded test execution, and context indexing.
Safety boundaries	Local-only web binding, credential masking, prompt-injection filtering, approval gates, and a hardened Docker command sandbox.

Fast start on Windows

Install Docker Desktop and Node.js 22 or later. Start Docker Desktop and wait until it reports that it is running. Then open the project folder and double-click the files below in order.

First release setup	Start Kairos	Stop Kairos
setup-kairos.bat	run-kairos.bat	stop-kairos.bat

The scripts deliberately pause after success and after failure so messages remain visible. Setup installs locked dependencies, creates a private .env file when necessary, prepares the Docker image, and keeps configuration out of version control. The run script starts the local control plane and opens the browser.

Release safety default: Docker Compose publishes the control plane only to 127.0.0.1. It is not exposed to your local network unless you deliberately change that setting.

Providers

Configure providers from the Providers page or through the CLI. Keys are stored locally and masked when displayed. In Docker Compose, provider configuration persists in the ignored data/ directory rather than inside the image.

Ollama: local models and direct Cloud models

For a local Ollama service, use the default endpoint and choose a locally installed model.

KAIROS_OLLAMA_BASE_URL="http://host.docker.internal:11434"
KAIROS_OLLAMA_MODEL="llama3.1"

For direct Ollama Cloud access, use Ollama's remote API endpoint and an API key created in the Ollama account settings. Ollama documents the direct cloud base URL as https://ollama.com/api and requires OLLAMA_API_KEY for programmatic cloud access. 1 2

KAIROS_OLLAMA_BASE_URL="https://ollama.com/api"
KAIROS_OLLAMA_API_KEY="your-private-ollama-api-key"
KAIROS_OLLAMA_MODEL="your-cloud-model"

Kairos uses the same Ollama chat API for local and cloud endpoints. When an Ollama API key is set, it sends it as an Authorization bearer credential; local Ollama continues to work without a key.

Other hosted providers

For Gemini, enter a Google AI Studio API key and select a supported model. Kairos sends this value through the x-goog-api-key header, not in the URL. For LM Studio or another local OpenAI-compatible service when Kairos runs in Docker, use the host bridge rather than container-local localhost.

http://host.docker.internal:1234/v1

MCP tools

Use the MCP page to register a server. Kairos supports stdio servers and HTTP MCP endpoints. Server environment values are stored in the local MCP configuration file with restrictive permissions where the operating system supports them, and are masked in the UI. Store only credentials you are authorized to use.

Workflow	What Kairos does
Register	Validates the server identity, transport, command/URL, arguments, limits, and environment-variable names.
Inspect	Sends a controlled initialize request and lists the server's advertised tools.
Invoke manually	Lets you supply JSON arguments through the local interface for a listed tool.
Invoke through the agent	The planner can propose an mcp_call; Kairos shows a review gate before calling the user-configured server. Tool results are prompt-injection scanned before entering agent context.

The included templates are starting points, not automatically installed dependencies. Review each MCP server's source, permissions, and environment needs before enabling it.

Skills and agent behavior

Kairos searches the local skills library for each goal and places the highest-relevance skill guidance into its planning context. Skills are guidance, not executable code: the agent treats skill documents and all tool output as untrusted content, scans them for prompt-injection patterns, and still applies the normal validation and approval rules.

The agent works from a limited action vocabulary: inspect files, write workspace files, run reviewed commands, execute tests, fetch public pages, open local previews, call approved MCP tools, use local data/crawler tools, and ask for clarification. Coding tasks must include both a write operation and a validation step.

Browser interface

For development without Docker:

npm ci
npm run kairos:dev -- web

Then open http://127.0.0.1:3210. The browser interface does not expose raw host-shell execution. Use the reviewed agent workflow or CLI for operations that could change files, run commands, or invoke MCP tools.

Crawler and AI Data

The crawler accepts one to three public http(s) URLs and produces a ZIP file containing a manifest and collected text. Private addresses, loopback URLs, credentials in URLs, oversized documents, and binary responses are rejected. The Data page profiles pasted CSV or JSON locally; it does not upload the dataset.

CLI quick reference

Run the commands below from the project root. Use npm.cmd on Windows when npm is not recognized.

npm run kairos:dev -- --help
npm run kairos:dev -- web
npm run kairos:dev -- providers list
npm run kairos:dev -- providers setup --provider ollama --yes
npm run kairos:dev -- brain status
npm run kairos:dev -- brain check
npm run kairos:dev -- skills list
npm run kairos:dev -- context build
npm run kairos:dev -- context search "security audit"
npm run kairos:dev -- sandbox status
npm run kairos:dev -- tools list

Command safety and Docker sandbox

Only a narrow read-only command set is low risk. Unrecognized commands are medium risk and require an interactive review. High-risk operations require the user to type APPROVE KAIROS in a real terminal. Flags cannot bypass medium- or high-risk review.

For agent CLI command execution, configure the command sandbox in .env:

KAIROS_COMMAND_SANDBOX="ubuntu-docker"
KAIROS_UBUNTU_IMAGE="ubuntu:24.04"
KAIROS_SANDBOX_NETWORK="none"
KAIROS_SANDBOX_WORKSPACE_MODE="rw"
KAIROS_SANDBOX_PULL="missing"
KAIROS_SANDBOX_USER="1000:1000"

The web container intentionally does not mount the Docker socket and does not expose arbitrary command execution in the browser. This separation prevents the control plane from becoming a host command console.

Local data and secrets

Deployment	Provider configuration	Working data
Development / CLI	.env in the project root	data/kairos by default
Docker Compose	/app/data/.env, mapped to local data/.env	Ignored local data/ directory

Do not commit .env, API keys, personal memory, crawl archives, MCP server secrets, or generated local data. Keep the project outside cloud-sync folders when possible.

Release checks

Run this full validation set before a release:

npm ci
npm run check
npm run check:ts
npm run lint
npm run build
npm test

License

Licensed under the Kairos Community License (KCL) v1.0. See LICENSE.

References