cognix
An open-source AI chat and agent platform you can host yourself.
Talk to any model, attach your files, connect MCP tool servers, build workflows,
and give agents a place to work — on infrastructure you control.
Quick start
Three variables. That is the whole configuration to get chatting:
git clone https://github.com/officialpriyam/cognix.git
cd cognix
cp .env.example .env
POSTGRES_URL=postgres://postgres:postgres@postgres:5432/cognix
BETTER_AUTH_SECRET= # npx @better-auth/cli@latest secret
AI_GATEWAY_API_KEY= # https://vercel.com/ai-gateway
docker compose -f docker/compose.yml up -d --build
Open http://localhost:3000 and create an account. The first account becomes the
administrator.
Why one model key? Models are served through the Vercel AI Gateway, which
fronts Anthropic, OpenAI, Google, Mistral, xAI, DeepSeek, Moonshot and more. You
manage one key and one bill instead of seven, and you can switch models
mid-conversation without touching configuration. If you would rather not use a
gateway at all, point the app at Ollama, LM Studio, or any OpenAI-compatible
endpoint — see Models.
Prefer running it directly? See docs/self-hosting.md.
What you get
Chat that does things. Streaming conversations with tool calling, file
attachments, image generation, and a sandboxed code runner. Mention an agent,
workflow, or tool with @ to pull it into the conversation.
Agents. Give an agent a role, instructions, and a set of tools. Share it
with your workspace or keep it private.
Skills. Reusable capabilities an agent loads on demand, so a large toolbox
does not have to sit in every prompt.
Projects with retrieval. Group chats, documents, and tools around a piece of
work. Uploaded documents are chunked, embedded, and searched with pgvector —
no external service required. Point a project at a knowledge base if you want
hosted retrieval instead.
Workflows. Build a graph of steps — LLM calls, conditions, HTTP requests,
code, templates — in a visual editor, publish it as a tool, and call it from any
chat.
MCP tool servers. Connect any Model Context Protocol server over HTTP or
stdio, with OAuth support, per-tool customization and a cached tool list.
Self-hosted instances can run stdio servers; the desktop app runs them locally.
Scheduled tasks. Have an agent run on a schedule and report back.
Voice. Realtime voice conversations through the gateway, plus transcription.
Desktop app. An Electron build that adds local MCP servers, filesystem
access, and the system keychain.
Model routing. Pick a model per message, or let the router choose from the
catalog based on the task.
Upgrading from 1.x
This is a new major version. The layout is now a monorepo, the environment is
different, and the schema has moved on considerably.
Back up your database first. Then:
pnpm install
pnpm tsx scripts/upgrade/from-cognix-1.ts --dry-run
pnpm tsx scripts/upgrade/from-cognix-1.ts --yes
The upgrade preserves your users, chats, agents, MCP servers and workflows.
Archives become projects, and the threads inside them stay linked. It is a
one-way migration — this is why the backup matters.
If you were setting per-provider API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY
and friends), replace them with a single AI_GATEWAY_API_KEY, or configure a
local provider.
Setup
Docker Compose
The quick start above. The bundled stack includes Postgres with
pgvector. Add --profile redis if you want resumable chat streams.
Local development
pnpm install # writes .env from .env.example
pnpm docker:pg # Postgres with pgvector on :5432
pnpm db:migrate # apply the schema
pnpm dev # http://localhost:3000
Postgres must have the pgvector extension — document embeddings are stored
as vector(1536). The bundled image has it; managed Postgres usually offers it
as a toggle.
Useful commands:
| Command | What it does |
|---|
pnpm check | Lint, typecheck and unit tests — run before committing |
pnpm test:e2e | Playwright end-to-end tests |
pnpm db:migrate | Apply pending migrations |
pnpm db:studio | Browse the database |
pnpm docker:redis | Redis for resumable streams |
Optional integrations
Everything below is off until you configure it. The server prints which
features are disabled at startup, so you always know why something is missing.
| Feature | Set | Without it |
|---|
| File uploads | SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, NEXT_PUBLIC_SUPABASE_URL | Attachments, avatars and generated images are disabled |
| Knowledge bases | AGENTSET_API_KEY | Knowledge bases unavailable; project documents still search locally with pgvector |
| Background jobs | INNGEST_SIGNING_KEY, INNGEST_EVENT_KEY | Scheduled tasks and the project brain need your own cron — see below |
| Resumable streams | REDIS_URL | A stream ends when the viewer navigates away |
| Code sandbox | E2B_API_KEY | Generated code runs in the in-browser worker only |
| Web search | EXA_API_KEY | The web search tool is unavailable |
| Voice transcription | ASSEMBLYAI_API_KEY | Realtime voice still works; transcription does not |
| Browser notifications | NEXT_PUBLIC_VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY | No notifications while the app is closed |
| Connected tools | COMPOSIO_API_KEY | Projects cannot connect third-party accounts |
| Observability | SUPERLOG_PUBLIC_TOKEN | Traces and logs stay local |
Running without Inngest. Scheduled tasks and the sandbox reaper are plain
HTTP endpoints. Set SCHEDULED_TASK_SECRET and call them from any cron:
curl -X POST https://your-instance/api/scheduled-tasks/cron \
-H "X-Scheduled-Task-Auth: $SCHEDULED_TASK_SECRET"
Models
The gateway is the default and covers the whole catalog. You can also:
- Run models locally. Connect Ollama, LM Studio, or any OpenAI-compatible
endpoint from the model picker. Nothing leaves your machine, and it needs no
server configuration — each account sets up its own.
- Use TensorX. An EU-hosted, zero-retention provider reached directly rather
than through the gateway. Set
TENSORX_API_KEY.
- Add any OpenAI-compatible provider with
OPENAI_COMPATIBLE_DATA:
pnpm openai-compatiable:init && pnpm openai-compatiable:parse.
Community
This edition, and the hosted one
cognix is the community edition of
Cognix. Everything above is here, in full,
with no usage caps and no telemetry.
What Navigator adds is what teams need and single users do not: shared team
workspaces with member management and invitations, per-member AI budgets and
org-wide model policy, billing, a managed workflow builder, and a Slack bot.
If you are running this for yourself or a small group, you are not missing
anything — that is the point.
License
MIT. See LICENSE.
Originally forked from officialpriyam/cognix,
whose work this is built on.
