English | 中文 | 日本語 | Français | Русский
Nova is a full-stack computer agent that researches, codes, creates, and defends. It orchestrates sub-agents, memory, and per-thread sandboxes — powered by extensible skills, a live streaming view of the agent's own computer, and a built-in security toolkit of 40 verified tools (blue team + red team).
Built by Ali Technologies on top of DeerFlow (MIT). Upstream license and all copyright notices preserved — see License and NOTICE.md.
- Quick Start
- Upgrading from a DeerFlow-named install
- What Nova adds on DeerFlow
- Security Arsenal -- blue team, red team, scanning
- Core Features
- Sandbox
- IM Channels
- Tracing
- Recommended Models
- Embedded Python Client
- CI/CD & Testing
- Contributing
- License
git clone https://github.com/Jahanzaib211/nova.git && cd nova
make setup # interactive wizard (~2 min)
make doctor # verify setup
make docker-start # or: make devAccess: http://localhost:2026
The Docker stack runs as Compose project nova (containers nova-gateway, nova-frontend, nova-nginx, …), keeps local data under backend/.nova/, and reads NOVA_* environment variables. Under PM2 the supervisor process is nova (scripts/pm2-nova.sh).
Earlier releases used the DeerFlow names: Python package deerflow, env vars DEER_FLOW_*, data dir .deer-flow, Compose project deer-flow-dev and containers deer-flow-*. Code changes alone break nothing — for one release:
import deerflow…anduse: deerflow.x:Ypaths inconfig.yamlstill resolve (deprecated alias ofnova);- every
NOVA_Xfalls back toDEER_FLOW_Xwhen unset; - an existing
.deer-flowdata dir is used when no.novadir exists (data is never moved automatically).
The infrastructure cutover (Compose project, containers, network and volumes, Postgres data included) is a separate, operator-run step:
scripts/migrate-deerflow-to-nova.sh # dry run (default): prints the plan, changes nothingThe script backs up first and copies volumes rather than moving them; the old deer-flow-* volumes are never deleted, so rolling back means bringing the old project up again. See the script's --help and the rename entry in NOVA_CHANGELOG.md.
make setup generates config.yaml + .env. Manual config: make config copies the full template.
Manual model configuration
models:
- name: gpt-4o
display_name: GPT-4o
use: langchain_openai:ChatOpenAI
model: gpt-4o
api_key: $OPENAI_API_KEY
- name: qwen3-32b-vllm
display_name: Qwen3 32B (vLLM)
use: nova.models.vllm_provider:VllmChatModel
model: Qwen/Qwen3-32B
api_key: $VLLM_API_KEY
base_url: http://localhost:8000/v1
supports_thinking: trueCLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API — see config.example.yaml.
| Target | Starting | Recommended |
|---|---|---|
Local dev (make dev) |
4 vCPU, 8 GB RAM, 20 GB SSD | 8 vCPU, 16 GB RAM |
Docker dev (make docker-start) |
4 vCPU, 8 GB RAM, 25 GB SSD | 8 vCPU, 16 GB RAM |
Production (make up) |
8 vCPU, 16 GB RAM, 40 GB SSD | 16 vCPU, 32 GB RAM |
make docker-init # pull sandbox image (once)
make docker-start # dev (hot-reload)
make up # production
make down # stop120,533 lines of new code across 698 new files. Total delta: +145,947 / −11,844 across 1,148 files. Audited 2026-09-08; every number reproducible — see NOVA_VS_DEERFLOW.md.
- Agent's Computer — 7-tab live panel: Files, Terminal, Editor (red/green diff), Browser preview, Telemetry, Review, Privacy. Real-time streaming.
- Verify loop — headless-Chromium self-checks against the running dev server. Console errors, blank-render detection, screenshots. Vision path so the model sees its build.
- Deterministic code review — no-LLM review engine. Plain-English verdict for non-coders, per-file stats and risk flags for devs.
- Self-correction middlewares — iteration budgets, dead-end loop detection, preflight quota checks, error decontamination, live task progress.
- 27 built-in agent tools (up from 2 at fork point, upstream still ships 3) — shell sessions, browser control, scaffold, dev-server lifecycle, code review, skill saving, and more.
- Runtime model management — add/switch models via API and settings UI.
- 4-layer sandbox image — base → tools → dind → android (10.2 GB → 20.4 GB). Go, Rust, Playwright, pandoc, tesseract, nested Docker daemon, full Android SDK. Pinned by digest.
- Global skill promotion — agent-authored skills security-scanned and promoted to global registry.
- Sub-agents and ACP runtimes — the lead agent fans work out to sub-agents; a chat can also run on Claude Code or OpenClaw over the Agent Client Protocol, driving the same sandbox and Agent's Computer, with fallback to the native agent if the runtime fails a turn.
- Run deadline and liveness — every run has a wall-clock deadline (
NOVA_RUN_MAX_SECONDS, default 2 h) and a liveness heartbeat; subagent timeouts are measured from dispatch. - Voice — self-hosted full-duplex speech (faster-whisper STT, Kokoro TTS, Silero VAD, optional semantic turn detection) with barge-in. Off by default; see docs/VOICE.md.
- Ops layer — self-healing watchdog, ops gates (runs/liveness, drift, upstream, capabilities, regression), PM2 lifecycle, reboot persistence, tunnel auto-recovery.
- Free models via LiteLLM — MiniMax M3, Nemotron 3 Super, Qwen3 Coder 480B, GPT-OSS 120B via Ollama.
- 38,782 lines of new tests — 152 backend test files + 53 frontend test files.
Nova ships a full-stack security capability: 40 security tools in every sandbox, verified by the regression gate on every image build (scripts/gates/regression-gate.py, SANDBOX_TOOLCHAIN), plus platform-level defenses and CI scanning.
Nova can build an app and then attack it — the full build-then-break loop in one agent:
- Build — scaffold a web app (Next.js, Flask, FastAPI, whatever) in the sandbox
- Self-audit — the verify loop catches console errors, blank renders, broken layouts
- Red team — the security skill spins up nuclei, nikto, sqlmap, dalfox, ffuf against the running dev server
- Report — deterministic code review + vulnerability scan output in one place
- Fix — agent patches the issues and re-verifies
This works on Nova's own builds or any app you point it at. Paste a URL or drop a repo into the sandbox and say "audit this" — the security skill handles the rest. Dependency-ordered attack chains: recon → web app scan → secret detection → exploitation attempts → forensics → hardening recommendations.
# Example: Nova builds a tip calculator, then probes it
> build a tip calculator with auth and a database
# Nova's agent does the build, then:
# - runs nuclei against localhost:3000
# - checks for SQL injection with sqlmap
# - fuzzes endpoints with ffuf
# - scans for XSS with dalfox
# - audits dependencies with trivy
# - outputs a security report
| Layer | What it does |
|---|---|
| AuthMiddleware | Fail-closed JWT auth gate on every request. Session versioning (revoke-all via token bump). |
| CSRFMiddleware | Double-submit cookie, timing-safe comparison, origin validation. |
| AuthRateLimitMiddleware | Sliding-window brute-force protection (10 attempts/60s auth, 60/60s cost). CIDR trust chain. |
| GuardrailMiddleware | Pre-tool-call authorization. Pluggable providers: AllowlistProvider, OAP policy, custom. Fail-closed default. |
| SandboxAuditMiddleware | Command classifier: block (rm -rf /, fork bombs, reverse shells, LD_PRELOAD), warn (chmod 777, sudo, pip install), pass. 100% high-risk recall, 0% false positive rate. |
| Path traversal protection | Multi-layer: ../, backslash, bare root, cd /, env var escapes, file:// URLs, brace expansion. |
| CSP headers | default-src 'self', sandbox allow-scripts allow-same-origin, X-Frame-Options: DENY. Active content forced as download. |
| Audit trail | Append-only admin_audit table. Auth events, sandbox operations, admin actions logged. |
| Secrets management | secrets-doctor.sh, secrets-export.sh (encrypted backup), K8s bootstrap. Env var resolution, Fernet-encrypted BYOK. |
| Dependency security | pip-audit, npm audit, Trivy container scanning, CodeQL SAST (Python + JS/TS), Dependabot. |
| Visitor security | Scanner/exploit probe detection, brute-force monitoring, high-4xx IP tracking. Grafana alerting. |
| Platform guardrails | CI enforcement: middleware sprawl detection, duplicate recovery, cross-reference isolation, blocking IO gate. |
| IDS | Suricata, in the sandbox image. |
| Hardening | Lynis (system audit) and chkrootkit (rootkit detection), in the sandbox image. |
Every tool below is baked into the sandbox image (docker/sandbox/Dockerfile.tools) and checked by the regression gate on each build. The security skill (skills/public/security/SKILL.md) maps them by domain with dependency-ordered chains: recon → web app → secrets → creds → forensics → hardening. A read-only methodology library (safe flags, scope rules, how to read output) is mounted at /mnt/security-toolkit.
| Domain | Tools (40) |
|---|---|
| Network | nmap, masscan, tshark |
| Vulnerability scanning | nuclei, trivy, nikto, wapiti, whatweb |
| Web app | sqlmap, gobuster, ffuf, dirb, dalfox (XSS) |
| Secrets | gitleaks, trufflehog, detect-secrets |
| Recon / OSINT | subfinder, httpx, amass, dnsrecon, sherlock, arjun |
| Credentials | hydra, john, hashcat, smbclient, impacket secretsdump.py |
| Forensics | binwalk, foremost, exiftool, yara, sleuthkit (fls), sslscan |
| Reverse engineering | ropper |
| Wireless | aircrack-ng, bettercap, wifite |
| Blue team | suricata, lynis, chkrootkit |
Deliberately not included: Metasploit and C2 frameworks, Semgrep (can be installed in-sandbox with pip install semgrep), theHarvester and enum4linux. The reasons are recorded in Dockerfile.tools. All testing must be authorized and in scope; see the methodology library.
| Tool | Where it runs |
|---|---|
| CodeQL | Semantic SAST (Python + JS/TS), weekly + every PR (codeql.yml) |
| Trivy | Container vulnerability scanning on release builds (container.yaml) |
| SBOM + cosign | Software bill of materials and signed images on release builds (container.yaml) |
| pip-audit / npm audit | Dependency vulnerability scanning (local-ci.yml) |
| Dependabot | Automated dependency updates |
cd backend && PYTHONPATH=. uv run pytest tests/test_sandbox_tools_security.py -v
cd backend && PYTHONPATH=. uv run pytest tests/test_guardrail*.py -v
cd backend && PYTHONPATH=. uv run pytest tests/test_sandbox_audit_middleware.py -v
python3 backend/tests/test_no_cross_references.py27 built-in agent tools. 27 public skills. Extensible via MCP servers and custom skills.
| Category | Skills |
|---|---|
| Research | deep-research, academic-paper-review, github-deep-research, systematic-literature-review |
| Code | code-reviewer, code-documentation, qa-tester, security |
| Data | data-analysis, chart-visualization |
| Content | newsletter-generation, ppt-generation, podcast-generation |
| Media | image-generation, video-generation, music-generation |
| Design | frontend-design, web-design-guidelines |
| Deploy | vercel-deploy-claimable |
| Trading | pine-script (TradingView Pine Script v5/v6) |
| Business | consulting-analysis |
| Meta | skill-creator, find-skills, bootstrap |
Skills load progressively — only when needed. Slash activation: /skill-name task.
| Tool | What it does |
|---|---|
get_ohlcv |
OHLCV candles — yfinance (equities/FX/futures), ccxt (crypto) |
compute_indicators |
SMA, EMA, RSI, MACD, ATR, ADX/DMI, Bollinger, VWAP |
backtest_signals |
Replays entry signals → win rate, expectancy, profit factor, max drawdown |
No API keys required. cd backend && uv sync --extra trading.
npx skills add https://github.com/Jahanzaib211/nova --skill claude-to-deerflowSend tasks, check status, manage threads — all from Claude Code.
Lead agent spawns sub-agents on the fly — scoped context, tools, termination conditions. Parallel when possible. Structured results synthesized into coherent output.
Persistent memory across sessions. Profile, preferences, writing style, technical stack. Stored locally, under your control.
Nova serves inference on AMD Instinct GPUs — built for the AMD Developer Hackathon (Act II).
- Fireworks AI (managed, AMD Instinct MI300X) and AMD Developer Cloud (vLLM on ROCm) as one-click presets.
GET /api/models/amd-usagereturns machine-readable AMD-usage summary.- Full setup: docs/AMD_INTEGRATION.md.
Three modes:
| Mode | Isolation | Use case |
|---|---|---|
| Local | Per-thread dirs, host bash disabled by default | Development |
| Docker | Container-based, resource caps | Recommended |
| Kubernetes | Pods via provisioner service | Production |
| Layer | Tag | Content | Size |
|---|---|---|---|
| 1 | nova-sandbox-base |
Upstream image, pinned by digest | 10.2 GB |
| 2 | nova-sandbox-tools |
pandoc, tesseract, Go, Rust, uv, pnpm, Playwright, psql, redis-cli | 18.5 GB |
| 3 | nova-sandbox-dind |
Nested Docker daemon (--privileged) |
18.8 GB |
| 4 | nova-sandbox-android |
OpenJDK 17, Android SDK, Gradle, Kotlin | 20.4 GB |
make sandbox-image # build the chain| Limit | Default | Purpose |
|---|---|---|
| Memory | 12g | Prevent host OOM |
| PIDs | 2048 | Fork bomb protection |
| CPU shares | 512 | Host starvation prevention |
| /dev/shm | 1g | Chromium render stability |
| Idle timeout | 3600s | Reclaim unused sandboxes |
| Max lifetime | null | Wall-clock ceiling (configurable) |
7 platforms. No public IP required for any.
| Channel | Transport |
|---|---|
| Telegram | Bot API (long-polling) |
| Slack | Socket Mode |
| Discord | Gateway WebSocket |
| Feishu / Lark | WebSocket |
| DingTalk | Stream Push (WebSocket) |
| Tencent iLink (long-polling) | |
| WeCom | WebSocket |
Commands: /new, /status, /models, /memory, /help.
LangSmith, Langfuse and local OTLP (Jaeger, Tempo, a self-hosted Langfuse, any OTLP collector) — any combination can run simultaneously. Trace correlation fields: session_id, user_id, trace_name, tags.
# LangSmith
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
# Langfuse
LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
# Local OTLP (nothing leaves the host unless you point it elsewhere)
NOVA_OTEL_TRACING=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318Model-agnostic. Best with: long context (100k+), reasoning, multimodal, strong tool-use.
from nova.client import NovaClient
client = NovaClient()
response = client.chat("Analyze this paper", thread_id="my-thread")
for event in client.stream("hello"):
if event.type == "messages-tuple" and event.data.get("type") == "ai":
print(event.data["content"])| Suite | Count | Command |
|---|---|---|
| Backend unit tests | 7,595 | cd backend && make test |
| Frontend unit tests | 881 | cd frontend && pnpm test |
| Playwright E2E | 183 | cd frontend && pnpm test:e2e |
| Blocking IO gate | 22 | cd backend && make test-blocking-io |
make ci # full local CI
make ci-fast # lint + tests only
make self-audit # full self-probe21 GitHub Actions workflows. Pre-commit hooks. CodeQL weekly + every PR.
- Fork → feature branch
make setup(Docker) ormake install(local)- Changes with hot-reload
cd backend && uv run pytest&&cd frontend && pnpm test- PR — CI runs format, lint, typecheck, tests
- Contributing Guide
- Configuration Guide
- Architecture Overview
- CI/CD Pipeline
- Troubleshooting
- Local Models
- Voice System
- Security Architecture
DeerFlow foundation: MIT License. All upstream copyright notices preserved.
Nova-specific additions (Agent's Computer UI, sandbox image, watchdogs, security arsenal, branding): proprietary — see NOTICE.md. Commercial license terms: alilabsx@gmail.com.
Built on DeerFlow by ByteDance. Powered by LangChain and LangGraph.
