Install the Nous agent with Docker

Clone the repository, put an Anthropic API key in .env and run docker compose up -d. Needs Docker Compose v2.

Read the quickstart guide

git clone https://github.com/tfatykhov/nous.git cd nous cp .env.example .env

Step 1 of 3clone Clone and configure NeedsDocker Compose v2 KeyANTHROPIC_API_KEY Thenstart the containers

# === REQUIRED === ANTHROPIC_API_KEY=sk-ant-... # === RECOMMENDED === OPENAI_API_KEY=sk-... BRAVE_SEARCH_API_KEY=BSA...

.envone key needed ANTHROPIC_API_KEY OrANTHROPIC_AUTH_TOKEN EmbeddingsOPENAI_API_KEY Web searchBRAVE_SEARCH_API_KEY

Get Nous on GitHub

What Nous needs before you start

Docker and one Anthropic key. The other keys switch on extra tools.

Docker and Docker Compose v2 Required
Anthropic API key Required, or a subscription token
OpenAI API key Recommended: embeddings for semantic search. Without it, search falls back to keywords.
Brave Search API key Recommended: turns on web_search
Telegram bot token Optional: the chat bot

.envfrom the quickstart

Docker Compose v2

Anthropic key

OpenAI key

Telegram token

ANTHROPIC_API_KEY=sk-ant-...required

OPENAI_API_KEY=sk-...recommended

BRAVE_SEARCH_API_KEY=BSA...recommended

TELEGRAM_BOT_TOKEN=123456:ABC-...optional

NOUS_ALLOWED_USERS=12345,67890optional

# DB_HOST=localhostDatabase defaults work for Docker

Nous quickstart in 3 steps

1. Clone and configure

Clone the repository and create .env in the project root with your ANTHROPIC_API_KEY.

$ git clone https://github.com/tfatykhov/nous.git
$ cd nous
$ cp .env.example .env
# set ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY enables embeddings

2. Start everything

One command starts PostgreSQL with pgvector, the agent and the Telegram bot. Migrations run on startup.

$ docker compose up -d
✔ Container nous-postgres   Started
✔ Container nous-agent      Started
✔ Container nous-scorer     Started
✔ Container nous-telegram   Started

3. Check it and say hello

Ask for its health, then send a first message. The dashboard runs at localhost:8000/dashboard.

$ curl http://localhost:8000/health
{"status":"healthy"}
$ curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, who are you?"}'

The containers Nous starts

The quickstart lists three. The compose file in 1.2.0 also starts nous-scorer, the job that scores background work.

nous-postgres pgvector/pgvector:pg17, port 5432
nous-agent Built from the Dockerfile, port 8000: REST and MCP
nous-telegram The chat bot; it exits at once without a token
nous-scorer Scores finished background subtasks

To skip the bot: docker compose up -d nous postgres

$ curl http://localhost:8000/status
# agent status, memory stats, calibration
$ docker logs nous-agent
# the agent's log
$ docker compose down
# stop; memory stays in the volume
$ docker compose down -v
# stop and remove data: a fresh start
$ uv sync && uv run python -m nous.main
# local development: Python 3.12+ and uv
$ uv run pytest tests/ -v
# tests need Postgres running

Three ways to talk to Nous

REST API on port 8000

Plain or streaming chat, plus routes for memory, decisions, identity, the heartbeat and DAGs.

POST /chatchat

POST /chat/streamSSE

GET /status

GET /decisions

GET /facts?q=query

GET /calibration

MCP server at /mcp

Other agents and tools reach Nous over the Model Context Protocol. It is on by default.

MCP tools5

nous_chat

nous_recall

nous_status

nous_teach

nous_decide

Telegram bot, optional

Set TELEGRAM_BOT_TOKEN, and NOUS_ALLOWED_USERS to limit who can talk to it.

Nousbot

YouWhy did last night's build fail?

NousNode 20 broke a native module. I pinned CI to Node 22 and the build passed.

AttachmentsImages, PDFs and text files

RepliesStreamed as they are written

Nous docs and questions

The repository's docs go deeper than this page.

tfatykhov/nous1.2.0

README.mdWhy Nous, features, how it thinks

docs/quickstart.mdDeploy, local development, every variable

docs/features/INDEX.mdEvery feature and its status

LICENSEApache 2.0

Can Nous run without Docker?

Yes, for development: start Postgres alone, then uv sync and uv run python -m nous.main.

Which Nous features are off by default?

Those marked opt-in in the README, such as approvals and coding jobs. Each sits behind a documented flag.

Can one database hold several agents?

Yes. Every row is scoped by agent_id; set NOUS_AGENT_ID per agent.

What should change for production?

The database password, at least. The quickstart lists a minimal production .env.