Skip to content
Ali-Labs-XPublic

About

Nova, the agent's computer: sub-agents, memory and a sandbox per thread. Built on DeerFlow + LangGraph.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

520 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Nova — The Agent's Computer

English | 中文 | 日本語 | Français | Русский

Python Node.js License: MIT CI CodeQL Dependabot Security

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.

Nova workspace — the agent builds a tip calculator and previews it live in the Agent's Computer Browser tab

Table of Contents

Quick Start

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 dev

Access: 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).

Upgrading from a DeerFlow-named install

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… and use: deerflow.x:Y paths in config.yaml still resolve (deprecated alias of nova);
  • every NOVA_X falls back to DEER_FLOW_X when unset;
  • an existing .deer-flow data dir is used when no .nova dir 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 nothing

The 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.

Configuration

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: true

CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API — see config.example.yaml.

Deployment Sizing

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

Docker

make docker-init    # pull sandbox image (once)
make docker-start   # dev (hot-reload)
make up             # production
make down           # stop

What Nova adds on DeerFlow

120,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.

Security Arsenal

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.

Probe Vibe-Coded Apps

Nova can build an app and then attack it — the full build-then-break loop in one agent:

  1. Build — scaffold a web app (Next.js, Flask, FastAPI, whatever) in the sandbox
  2. Self-audit — the verify loop catches console errors, blank renders, broken layouts
  3. Red team — the security skill spins up nuclei, nikto, sqlmap, dalfox, ffuf against the running dev server
  4. Report — deterministic code review + vulnerability scan output in one place
  5. 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

Blue Team (Defensive)

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.

Sandbox Security Toolkit

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.

Security Scanning (CI)

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

Running Security Tests

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.py

Core Features

Skills & Tools

27 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.

Trading & Market Data

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.

Claude Code Integration

npx skills add https://github.com/Jahanzaib211/nova --skill claude-to-deerflow

Send tasks, check status, manage threads — all from Claude Code.

Sub-Agents

Lead agent spawns sub-agents on the fly — scoped context, tools, termination conditions. Parallel when possible. Structured results synthesized into coherent output.

Long-Term Memory

Persistent memory across sessions. Profile, preferences, writing style, technical stack. Stored locally, under your control.

Runs on AMD Compute

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-usage returns machine-readable AMD-usage summary.
  • Full setup: docs/AMD_INTEGRATION.md.

Sandbox

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

Sandbox Image Chain

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

Resource Limits

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)

IM Channels

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)
WeChat Tencent iLink (long-polling)
WeCom WebSocket

Commands: /new, /status, /models, /memory, /help.

Tracing

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:4318

Recommended Models

Model-agnostic. Best with: long context (100k+), reasoning, multimodal, strong tool-use.

Embedded Python Client

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"])

CI/CD & Testing

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-probe

21 GitHub Actions workflows. Pre-commit hooks. CodeQL weekly + every PR.

Contributing

  1. Fork → feature branch
  2. make setup (Docker) or make install (local)
  3. Changes with hot-reload
  4. cd backend && uv run pytest && cd frontend && pnpm test
  5. PR — CI runs format, lint, typecheck, tests

Documentation

License

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.

Acknowledgments

Built on DeerFlow by ByteDance. Powered by LangChain and LangGraph.

Star History

Star History Chart

About

Nova, the agent's computer: sub-agents, memory and a sandbox per thread. Built on DeerFlow + LangGraph.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages