Deploy Polaris: Open-Source AI Research Agent for Your Lab

Most "AI research assistants" are chatbot wrappers: they read a paper, answer questions, maybe draft a paragraph. Polaris, open-sourced this week by the ZJU-REAL lab at Zhejiang University, is the opposite. It runs the entire research lifecycle as one system — literature survey, idea generation, idea review, GPU experiments, LaTeX paper writing, and paper review — and each stage produces artifacts the next stage consumes, with every hand-off able to pause at a human approval gate.

The engineering decision worth stealing: the heavy lifting (crawling, parsing, deduplication, metric parsing, citation matching) is deterministic code. LLMs are reserved for judgement calls — scoring, synthesis, drafting, review. That split keeps runs cheap, reproducible, and auditable, which is exactly the pattern you want for any serious agent project.

Six stages, one pipeline, plus a Voyage agent core

• Literature: ingests papers from OpenAlex, Semantic Scholar, and arXiv. Cold start snowballs citations from anchor papers, then compiles a cross-linked wiki page per paper (TL;DR, method, reusable ideas, concept backlinks) — one wiki per paper, shared platform-wide, so a paper never reads differently depending on where you opened it.
• Idea: multi-signal gap analysis over the knowledge base (concept co-occurrence holes, extracted limitations, trend velocity) drives retrieval-planned idea generation. Ideas are scored on novelty, feasibility, operability, impact.
• Idea review: reviewer agents with configurable personas debate pairwise; a judge produces an Elo tournament ranking. Lab members join live over WebSocket, and their comments enter the agent context as first-class input.
• Experiment: Fernet-encrypted SSH credentials reach your lab GPU servers. An experiment Voyage asks intake questions, plans the study, passes a compute-budget check, writes code, runs a smoke test, launches runs with streamed logs and live metric curves, then auto-iterates — parse metrics, reflect, improve or stop — repairing failures under a time budget rather than a fixed retry count. When it is genuinely stuck, it asks the user instead of failing.
• Paper writing: multi-file LaTeX project (NeurIPS/ICLR/ACL templates) with a CodeMirror 6 editor, real-time CRDT collaborative editing, and server-side tectonic compilation to a live PDF. Experiment numbers may only come from real run metrics; citations must map to real knowledge-base entries.
• Paper review: citation checking before the submission gate.

Every long task runs as a Voyage: a persisted, resumable, human-gated agent run that can span hours or days without losing state. This is the architecture to copy — long-running agent work as auditable, restartable runs, not fire-and-forget calls.

Get it running in two commands

Docker Compose is the recommended path, in development and production — no local Python, Node, or database needed:

cp .env.example .env        # set provider keys and secrets
make dev                    # full stack via docker compose, hot reload

Frontend at http://localhost:5173, API docs at http://localhost:8000/docs. For production, use the pre-built Docker Hub images — no local build:

cp .env.example .env        # POLARIS_ENV=prod, POLARIS_IMAGE_TAG, secrets, LLM key
docker compose --env-file .env -f docker/docker-compose.yml pull
docker compose --env-file .env -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml exec api alembic upgrade head   # required on first run

Three gotchas: the worker container is mandatory (it runs all long tasks); the first-run migration is required because Postgres tables are not auto-created; and the repo-root .env drives POLARIS_ENV, POLARIS_IMAGE_TAG, and your model provider keys.

Model routing: one LLM boundary, DB-driven

All model calls go through a single abstraction layer. A DB-backed routing table maps each research stage to a provider, a model, and a reasoning-effort level — cheap models for scoring, strong models for debate and drafting. Admins set global routes; individual users can override their own. Model choice is configuration, not hard-coded, and the built-in fake provider is structurally disabled in production. Steal this for any multi-stage agent system.

Expose your research stack to Claude Code via MCP

Polaris ships a read-only MCP server (Streamable HTTP and stdio) exposing literature, knowledge, project state, manuscripts, and external search. Point Claude Code, Codex, or Cursor at it and your agent tools can query the research wiki directly. Every tool has a self-check and a try-it playground, so you can test before wiring it in. It is a clean pattern for giving external coding agents read-only access to a domain knowledge base — the same direction agent traffic is heading generally.

Practical advice

• Tour the live demo first: sign in at http://101.37.174.109:8080 with guest / zjuguest123 — read-only, no model calls, but every screen including admin views.
• Copy the deterministic-vs-judgement split. It is why runs are cheap enough to leave running for hours.
• Treat every long task as a resumable run with human gates and a file-based memory across steps.
• Desktop clients (macOS/Windows/Linux) come from the Releases page. Builds are unsigned: macOS needs xattr -dr com.apple.quarantine once, Ubuntu 24.04 may need --no-sandbox.

Resources

• GitHub: github.com/ZJU-REAL/Polaris (Apache 2.0, Docker Compose, live demo)
• Docs: getting-started, architecture, concepts, deployment, configuration — all in the repo docs/ folder
• Related reading: MCP goes stateless: agent traffic becomes plain HTTP