cognis

Cloud-native Agent OS for self-hosted AI agents. Cognis gives agents identity, memory, workflows, tools, browser use, channels, and safety guardrails without turning everything into one fragile monolith.

Cognis separates the controller from executors. The controller is the brain: it owns users, agents, conversations, workflows, memory context, guardrails, routing, and the UI. Executors are the hands: they run tools, browsers, shells, LSPs, MCP servers, and optional local inference wherever the work should happen: on your laptop, in a private network, or in the cloud.

Cognis works with companion services for memory and guardrails:

• Intaris for guardrails, audit, and session content
• Mnemory for persistent memory and recall

Why Cognis

• Agent work should not block chat. Research, coding, browser sessions, and multi-step tasks can run in background workflows while the main conversation stays responsive.
• Tools should run near the thing they touch. A cloud controller can orchestrate an executor in your home lab, a customer VPC, a CI runner, or a disposable container.
• Browser use should be real. Executors can drive Playwright/Patchright browsers, keep persistent local profiles, inspect pages, click, type, submit forms, save screenshots, and behave closer to a human using a site than a simple HTTP scraper.
• Memory and safety should be first-class. Cognis integrates Mnemory for long-term recall and Intaris for guardrails, approvals, audit, and session history.
• Work should be structured. Tasks, workflows, gates, deliverables, revisions, schedules, and project context make agents useful for repeatable operations instead of one-off prompts.

What You Can Build

• A personal agent workspace with chat, web research, browser automation, task queues, and scheduled workflows.
• A team controller with remote executors in different networks, each exposing only the tools it should run.
• Agents that monitor channels, ask for approval, perform browser tasks, and deliver results back to conversations.
• Project-aware coding or research workflows that know which repository, source, task, or workflow they belong to.
• Skill-backed agents that can load reusable operating procedures and tool bundles only when needed.

Screenshots

Desktop workspace:

Realtime tool call rendering:

iOS PWA:

Features

• Streaming chat workspace: WebSocket chat with token streaming, tool activity, todos, approvals, delegation cards, reconnect handling, search, timestamps, and mobile-friendly navigation.
• Agent identity: Agents have names, descriptions, personality, behavioral guidance, model/provider overrides, skills, avatars, sharing rules, and executor/tool boundaries.
• Projects: Group work around projects with source hints, workflow bindings, grants, project-aware tasks, schedules, conversations, and context injection for relevant paths.
• Tasks and workflows: Durable task board, dependencies, priorities, step runs, gates, deliverables, comments, reruns, revisions, schedules, and reusable workflow templates.
• Remote executors: In-process, subprocess, and WebSocket executors. Use stateless cloud executors for ephemeral work or persistent executor homes for browser profiles, workspaces, caches, and local identity.
• Browser and web tools: Web search/fetch/crawl/map/research plus executor-native browser sessions, snapshots, queries, clicks, typing, forms, console/network inspection, screenshots, and saved auth state.
• MCP and native tools: Built-in filesystem, shell, search, LSP, artifact, image, date/time, memory, browser, web, Office document, workflow, and system tools, plus MCP tools from controller-managed or executor-attached servers.
• Skills: Versioned instruction, asset, and tool bundles. Agents discover compact skill metadata, load full instructions on demand, and can expose linked or bundled tools through the executor boundary.
• Memory: Mnemory-backed recall and remember for user facts, agent personality, episodic memory, and artifacts.
• Knowledgebases: Optional artifact-backed retrieval over Qdrant native dense+sparse hybrid search, with built-in agent tools for create/attach/index/search/source-context workflows.
• Guardrails and approvals: Intaris evaluates tool calls, escalates sensitive actions, records session content, and keeps an audit trail.
• Credentials without prompt leakage: Secrets are encrypted at rest and referenced through value refs. Agents and LLMs receive references, not raw secret values; executors resolve values only at execution time.
• Channels: Connect agents to external platforms through channel accounts, verified contacts, webhook/gateway adapters, and pairing flows. Signal and iMessage via BlueBubbles have the most complete setup paths today.
• PWA and mobile UX: Installable web app with offline shell, iOS/Android safe-area layout, bottom tabs, drawers, and task/workflow views tuned for small screens.
• Admin and operations: Setup flow, diagnostics, provider presets, model routing, secrets, executor tokens, system health, metrics, reconciliation, CLI admin commands, Docker images, and systemd templates.

Architecture

The important rule is simple: the controller decides, executors do. Even local development uses the same conceptual boundary. This is what lets Cognis run as a cloud-native controller while moving risky, stateful, or network-local work to executors.

Quick Start

Python package split

cognis-controller is the control plane. A plain installation is remote-WebSocket-only: it does not install the local executor, its tools, or its runtime dependencies.

pip install cognis-controller

For local in-process or subprocess execution, install the executor package too. The full extra is the normal full-capability installation:

pip install "cognis-controller" "cognis-executor[full]"

There is no local-executors extra. The official controller Docker image is intentionally remote-only; connect an external or sidecar cognis-executor[full] executor when the controller needs tool execution.

Prerequisites

• Python 3.12+
• One LLM option: OpenAI, Anthropic, OpenAI-compatible API, LiteLLM proxy, or local Ollama
• Mnemory and Intaris for memory and guardrails

Start Cognis once so it creates local state and a setup URL:

uvx cognis-controller

On first start Cognis creates ~/.cognis/ with ES256 JWT keys, a secrets encryption key, and a SQLite database. It serves the bundled UI on http://localhost:8080 when assets are available.

Start the companion services with Cognis's public key:

MNEMORY_JWT_PUBLIC_KEY=~/.cognis/keys/public.pem uvx mnemory
INTARIS_JWT_PUBLIC_KEY=~/.cognis/keys/public.pem uvx intaris

Restart Cognis with an LLM credential if needed:

OPENAI_API_KEY=sk-... uvx cognis-controller

Then open the printed setup URL, create the first admin user, and use the in-app Getting started checklist to configure:

1. Provider and model routing
2. Executor/tool access
3. First agent
4. First chat or task

For headless setup:

cognis-controller admin create-user admin@example.com --name "Admin"

macOS executor

Homebrew is the recommended way to install an executor on macOS:

brew tap fpytloun/tap
brew install cognis-executor
cognis-executor configure
cognis-executor start

The formula uses Google Chrome from the system and runs as a per-user launchd service. See the macOS executor guide for configuration, diagnostics, logs, upgrades, and source development installs.

Docker

Cognis publishes two images:

• ghcr.io/fpytloun/cognis for the remote-only controller and bundled UI
• ghcr.io/fpytloun/cognis-executor for WebSocket executors with browser, shell, coding, search, and LSP tooling

The controller image cannot execute host tools. It must connect an external or sidecar executor. Local executor rows persisted in the controller database remain unavailable until a compatible executor package/process is installed and connected.

Run the controller with persistent state:

docker run -d \
  --name cognis \
  --add-host=host.docker.internal:host-gateway \
  -p 8080:8080 \
  -v cognis-data:/data \
  -e COGNIS_DATA_DIR=/data \
  -e COGNIS_MNEMORY_URL=http://host.docker.internal:8050 \
  -e COGNIS_INTARIS_URL=http://host.docker.internal:8060 \
  -e OPENAI_API_KEY=sk-... \
  ghcr.io/fpytloun/cognis:latest

Create a WebSocket executor in Settings -> Executors, generate a token, then run an executor:

docker run -d \
  --name cognis-executor \
  -v cognis-executor-home:/home/cognis \
  -e COGNIS_CONTROLLER_URL=wss://cognis.example.com/api/executor/ws \
  -e COGNIS_EXECUTOR_TOKEN=eyJ... \
  ghcr.io/fpytloun/cognis-executor:latest

latest is the recommended general executor image. It includes browser, document, MCP, Git, uvx, and npx support. Use the minimal tag only when you intentionally need a reduced system tool set. Use development when you also need preinstalled language servers.

For a local non-TLS controller, use ws://localhost:8080/api/executor/ws only with local networking. Remote executors should use wss://.

See Deployment for production notes, and High Availability for Helm topology, rolling upgrades, failure semantics, and the operator checklist.

Configuration

Cognis has no config file. Infrastructure settings use environment variables; application settings live in the database and are managed through the UI/API.

Common variables:

Optional Knowledgebases can index Cognis artifacts into a vector backend. They remain hidden/unavailable unless both COGNIS_KNOWLEDGEBASE_VECTOR_BACKEND is set to a supported backend such as qdrant and model routing has an embedding route. See docs/specs/knowledgebase.md for the current API/configuration notes.

Auto-generated unless overridden:

• COGNIS_JWT_PRIVATE_KEY_PATH
• COGNIS_JWT_PUBLIC_KEY_PATH
• COGNIS_SECRETS_KEY_PATH

CLI

cognis-controller serve
cognis-controller admin create-user <email>
cognis-controller admin reset-password <email>
cognis-controller admin api-key create <email>
cognis-controller status
cognis-controller config init

Remote executor:

cognis-executor \
  --controller-url wss://cognis.example.com/api/executor/ws \
  --token <jwt-token>

Environment variables are preferred for long-running executors so tokens do not appear in command history:

export COGNIS_CONTROLLER_URL=wss://cognis.example.com/api/executor/ws
export COGNIS_EXECUTOR_TOKEN=<jwt-token>
export COGNIS_EXECUTOR_WORKDIR=~
cognis-executor

Executor package

Install a normal remote executor with the complete component set:

pip install "cognis-executor[full]==0.14.0"
uvx --from 'cognis-executor[full]' cognis-executor

Use bare cognis-executor for a minimal filesystem/shell/search executor, or select the browser, mcp, web, documents, inference, and channels extras as needed.

Development

uv pip install -e ".[dev]"
uv run cognis-controller serve

uv run pytest tests/unit/ -v
uv run pytest tests/contract/ -v
uv run pytest tests/integration/ -v

cd ui && npm install && npm run check && npm run test && npm run build

ruff check cognis/ tests/
ruff format cognis/ tests/
mypy cognis/

Status

Available today:

• Chat, agents, projects, tasks, workflows, schedules, channels, tools, skills, and bundled web UI
• In-process, subprocess, and remote WebSocket executors
• Executor-routed inference and executor-native browser automation
• Mnemory and Intaris integrations
• MCP tools, encrypted secrets, credential references, setup diagnostics, admin CLI, Docker images, and systemd templates

Still ahead:

• Docker and Kubernetes executor backends managed directly by the controller
• Federation and cryptographic agent identity
• Broader multi-replica and multi-user production hardening

Documentation

• Documentation Index
• Getting Started
• Architecture
• Projects
• Configuring Providers
• Creating Agents
• Using Chat
• Managing Tasks
• Schedules
• Workflows
• Tools and Skills
• Channels
• Executors
• Deployment
• High Availability
• Security and Privacy
• Troubleshooting
• Internal Design Specs
• OfficeCLI Executor-Native Office Tools

License

Business Source License 1.1, same licensing model as Intaris.

• Free for your own internal business operations, including internal deployment
• Modifications and redistribution allowed when not used commercially
• Converts to Apache License 2.0 on 2030-03-15

See LICENSE for the full terms.