Nodus

v4.2.0 stable on PyPI — pip install nodus-lang · Full 32-package companion ecosystem live: pip install nodus-sdk[agent,sql,fastapi]

[!IMPORTANT]

Breaking in the next release: NodusRuntime denies capabilities by default

Embedding only. A NodusRuntime() can no longer run subprocesses, open sockets, or read the process environment unless you say so:

# before — worked
NodusRuntime().run_source(script)

# now — grant what the script actually needs
NodusRuntime(allow_subprocess=True, allow_network=True).run_source(script)

The error names the flag: Blocked: subprocess execution is not granted; pass allow_subprocess=True to NodusRuntime to allow it

nodus run is unaffected. A script you wrote and chose to run is not the threat model; hosting code you did not author is. The CLI never constructs a NodusRuntime.

Also: a Nodus program can no longer write into .nodus/ — the workflow store and graph state — because it could previously forge run records.

Why: all three external architecture audits found the same thing — the capability chokepoint was built and unused, with "the door propped open by registering subprocess and http by default." See the migration note and #405.

Recent: 4.2.0 is a correctness release — finally now runs when catch re-throws, std:async worker pools actually run their workers, --help no longer executes the command it documents, and the embedded runtime applies a call-depth cap by default. It also adds an opcode-freeze gate phase and DAP locals. See the changelog.

pip install nodus-lang
nodus init
nodus run
nodus repl

Nodus is an orchestration DSL and embedded runtime for hosting agentic systems, created by Shawn Knight as part of the Masterplan Infinite Weave ecosystem. Its execution model embodies the Infinity Algorithm's feedback-loop structure at the runtime layer — a structural correspondence documented in Infinity Pattern Mapping, not a named construct in the grammar.

There is no model in the core, and that is the design. Nodus contains no LLM client, no agent loop and no tool-selection logic; action agent "name" with {...} hands a JSON-safe payload to a handler your host registers, and takes a result back. Because the runtime cannot perform inference, every semantic decision must cross that boundary — so deterministic structure never guesses, and the model never controls sequencing.

What the language contributes: workflow, goal, step and after are real keywords with real AST nodes, and dependency names are resolved and checked at parse time — after typo is a syntax error, which LangGraph, Prefect and Airflow all discover at run time. Coroutines are a hybrid: one YIELD opcode and a VM-level Coroutine that saves ip/stack/frames, with spawn/channel/send/recv as builtins. Task graphs are a runtime library (orchestration/task_graph.py) operating on data the compiler emits — genuine deterministic sequencing, but not language-level, and the README said otherwise until v4.2.0.

If you're building multi-step AI agents, embedding a scripting layer in a Python application, or wiring together tools via MCP or A2A (through the nodus-mcp and nodus-a2a companion packages — the core language ships neither protocol), Nodus is the execution layer.

For a machine-readable project index see llms.txt.

Beyond the core language, the Nodus ecosystem spans 32 standalone companion packages published on PyPI (33 projects counting nodus-lang itself), all with source at github.com/Masterplanner25. A unified SDK (nodus-sdk) provides a single installation story: pip install nodus-sdk[agent,sql,fastapi]. See the ecosystem guide for the package-by-package breakdown.

Editor and CI integrations ship separately: the VS Code extension (syntax, LSP, debugger), the Jupyter kernel, and the nodus-run GitHub Action.

Install

Requires Python 3.10+.

pip install nodus-lang

Optional extras:

pip install "nodus-lang[server]"   # FastAPI + Uvicorn — nodus serve
pip install "nodus-lang[http]"     # httpx — std:http
pip install "nodus-lang[schema]"   # pydantic — syscall/extension schema validation
pip install "nodus-lang[retry]"    # nodus-retry — durable effect store for std:retry

Without [retry], std:retry falls back to the built-in in-memory effect store.

Quick Start

Create a project:

mkdir my-app
cd my-app
nodus init
nodus run

nodus init creates nodus.toml and src/main.nd.

nodus run executes the current project's src/main.nd when run inside a project root.

Start the REPL:

nodus repl

Useful REPL commands:

• :help shows REPL commands.
• :quit exits the REPL.

Run A File

Create hello.nd:

print("hello")

Run it explicitly:

nodus run hello.nd

When you provide a file path, Nodus runs only that file. When you run nodus run with no file inside a project, Nodus runs only src/main.nd.

Common Commands

• nodus --version
• nodus run hello.nd / nodus run — run a file, or the current project's entry point
• nodus check hello.nd / nodus check — validate syntax and imports without executing
• nodus fmt hello.nd — format in place
• nodus test — run *_test.nd / test_*.nd files
• nodus repl — interactive shell
• nodus status — show the project and entry point for the current directory
• nodus stability — show which language surfaces are stable vs experimental

nodus --help lists the rest: project and dependency management (init, add, install, deps), inspection (ast, dis, debug, profile), orchestration (workflow, goal-run, graph run), the HTTP server (serve, worker), and the LSP/DAP servers (lsp, dap) used by the editor integrations.

Standard Library

Import standard library modules with the std: prefix:

import "std:http" as http
let r = http.get("https://api.example.com/data")
print(r.body)

The standard library ships with Nodus — no extra installs for core modules (std:http is the one exception; it needs the [http] extra above). Full reference: Standard Library guide.

Networking, processes, and the filesystem

Data and encoding

Time and system

Concurrency (experimental)

channel(), send(), recv(), close(), spawn(), and coroutine() are VM built-ins — always available, no import needed.

AI-native orchestration (v4.0)

Testing

Documentation

• User Guide — task-oriented walkthroughs; index in §7
• Language Specification — full syntax, types, control flow, imports, coroutines
• Embedding Nodus — NodusRuntime from Python, sandboxing, limits
• Ecosystem Specs - implementation specs for proposed Nodus libraries and frameworks
• Architecture — runtime pipeline and module system
• Changelog — version history
• Contributing — development setup, code style, and contribution process
• llms.txt — machine-readable project index for AI tools
• llms-full.txt — full content summaries for AI indexers

Using with Claude Code

If you write Nodus with Claude Code, a language skill is available that teaches Claude the idioms, gotchas, and workflow patterns specific to Nodus v4:

1. Download skills/nodus.skill and skills/project-CLAUDE.md from this repo.
2. Copy project-CLAUDE.md to your project root as CLAUDE.md (fill in your project name).
3. Drop nodus.skill in your project's .claude/commands/ folder.
4. Claude will apply Nodus-specific rules automatically in every session.

The skill covers: record vs map distinction, the closure outer-let pattern, spawn() coroutine wrapping, workflow result bracket notation, NodusRuntime embedding defaults (timeout_ms=None, allowed_paths=CWD since v4.0.1), the stdlib module surface, and 15 verified complete example programs.

Using with Codex

If you write Nodus with Codex, a Codex-native skill and project template are available:

1. Copy skills/project-AGENTS.md to your project root as AGENTS.md and fill in your project name if needed.
2. Copy the skills/nodus/ folder to $CODEX_HOME/skills/nodus or ~/.codex/skills/nodus.
3. Start a Codex session in your Nodus project. Codex can auto-trigger the skill, or you can invoke $nodus explicitly.

The Codex skill covers the same core language hazards: record vs map distinction, closure outer-let mutation, spawn() coroutine wrapping, workflow result bracket notation, import rules, and NodusRuntime embedding defaults (timeout_ms=None, allowed_paths=CWD since v4.0.1), while keeping deeper material in reference files for on-demand loading.

Creator & Ecosystem

Nodus is created and maintained by Shawn Knight as part of the Masterplan Infinite Weave — an AI-native execution framework built on the Infinity Algorithm. Nodus is the runtime layer whose execution model embodies the Infinity Algorithm's orchestration structure (see Infinity Pattern Mapping).

From the creator's writing:

• Why I'm Building A.I.N.D.Y. (Or Any Tool, Really) — the strategic context behind Nodus
• Duality of Progress: Master Index — the Infinity Algorithm framework Nodus executes
• AI Search Optimization — the discoverability philosophy this project embodies