pynydus 0.0.7

Portable state transport for AI agents

Portable state transport for AI agents
Transport agent state between any two frameworks without manual migration

Docs • Install • How it works • CLI • Python SDK • Development

---

How it works

• Spawn: read source agent artifacts, redact PII, and package everything into a portable Egg (.egg archive)
• Hatch: decode an Egg into any supported target runtime, with optional LLM refinement and secret injection

Source artifacts → Spawn → Egg (.egg) → Hatch → Target-native files

The Egg format

An .egg file is a signed ZIP archive containing:

manifest.json          # metadata, neutral fields, versions
memory.json            # labeled memory records
secrets.json           # PII placeholders + secret requirements
skills/<slug>/SKILL.md # portable skill definitions (agentskills.io)
mcp.json               # MCP server configs (Claude Desktop format)
agent-card.json        # A2A agent card
AGENTS.md              # per-egg deployment runbook
apm.yml                # APM manifest (passthrough, if present)
specs/                 # embedded spec snapshots for self-sustained eggs
raw/...                # redacted source files (for passthrough mode hatch)

Agentic standards

Nydus integrates with five agentic standards. Each has a spec file in specs/, validation against its schema, and an extract CLI command:

Standard	Spec source	Egg artifact
MCP	specs/mcp.md	mcp.json
Agent Skills	specs/agentskills.md	skills/<slug>/SKILL.md
A2A	specs/a2a.md	agent-card.json
APM	specs/apm.md	apm.yml
AGENTS.md	specs/agents.md	AGENTS.md

Install

pip install pynydus

Prerequisites

Gitleaks is required for spawning when REDACT true (the default) and SOURCE directives are present. Gitleaks scans source files for secrets (API keys, tokens, passwords). Install it before running nydus spawn:

# macOS
brew install gitleaks

# Linux (download from GitHub releases)
curl -sSL https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_8.21.2_linux_x64.tar.gz \
  | tar xz -C /usr/local/bin gitleaks

# Or build from source (requires Go 1.22+)
go install github.com/gitleaks/gitleaks/v8@latest

If gitleaks is installed in a non-standard location, set NYDUS_GITLEAKS_PATH:

export NYDUS_GITLEAKS_PATH=/opt/bin/gitleaks

Hatching (and FROM-only spawns without SOURCE) does not require gitleaks.

CLI

# Create a Nydusfile in your project directory
cat > Nydusfile << 'EOF'
SOURCE openclaw ./my-agent/
REDACT true
EOF

# Spawn an egg
nydus spawn -o agent.egg

# Inspect (includes inline validation)
nydus inspect agent.egg
nydus inspect agent.egg --secrets --logs

# Extract standard artifacts
nydus extract mcp --from agent.egg -o ./out
nydus extract skills --from agent.egg -o ./out
nydus extract a2a --from agent.egg -o ./out
nydus extract apm --from agent.egg -o ./out
nydus extract agents --from agent.egg -o ./out
nydus extract specs --from agent.egg -o ./specs
nydus extract all --from agent.egg -o ./extracted

# Generate a template .env from the egg's secret requirements
nydus env agent.egg -o agent.env

# Hatch into a target runtime
nydus hatch agent.egg --target letta --secrets agent.env

# Compare two eggs
nydus diff v1.egg v2.egg

# Signing
nydus keygen
nydus spawn -o signed.egg  # auto-signs if key exists

Python SDK

from pathlib import Path

from pynydus import Nydus
from pynydus.common.enums import AgentType

ny = Nydus()

# Spawn from a Nydusfile in the current directory
egg = ny.spawn()
ny.save(egg, Path("agent.egg"))

# Load and hatch into a target runtime
egg = ny.load(Path("agent.egg"))
result = ny.hatch(egg, target=AgentType.LETTA, secrets="agent.env")
print(result.output_dir, result.files_created)

Project structure

pynydus/
  api/           # Egg data model, schemas, protocols (Spawner/Hatcher ABCs), errors
  agents/        # Per-platform spawners + hatchers (openclaw, zeroclaw, letta)
  engine/        # Core pipelines: spawn, hatch, save/load egg, diff, merge, refine, validate
  standards/     # Per-standard modules: mcp, skills, a2a, apm, agents_md (validate/extract/generate)
  security/      # Presidio, gitleaks, Ed25519 signing
  cmd/           # Typer CLI (spawn, hatch, inspect, extract, diff, env, keygen, push/pull)
  client/        # Python SDK (Nydus class)
  common/        # Shared enums, connector helpers, scan_paths
  llm/           # LLM tier models and Instructor client
  config.py      # Environment-based config loader
  remote/        # Nest registry client
  eggs/base/     # Base egg source definitions (Nydusfile + agent files per version)
specs/           # Spec files with embedded JSON Schema (mcp, agentskills, a2a, apm, agents)
tests/
  unit/          # Unit tests (mocked dependencies)
  integration/   # Integration tests (full pipeline, requires gitleaks)

Configuration

Set environment variables for LLM refinement and the Nest registry. Copy [.env.example](.env.example) to .env and fill in your values. See the Configuration doc for all available settings (NYDUS_LLM_TYPE, NYDUS_LLM_API_KEY, NYDUS_REGISTRY_URL, etc.).

Development

uv sync --group dev

Tests

Tests are split into tests/unit/ and tests/integration/ with dedicated Make targets:

make test-unit          # fast, no external deps
make test-integration   # full pipeline, requires gitleaks
make test               # both (excludes live LLM)
make test-live-llm      # requires .env with NYDUS_LLM_TYPE + NYDUS_LLM_API_KEY

Integration tests require gitleaks on PATH (see Prerequisites).

For live LLM tests, copy .env.example to .env and fill in your API key. The .env file is loaded automatically by pytest-dotenv.

Code style

make fmt          # Ruff formatter + auto-fix lint
make check        # Ruff format check + lint (no writes)

Docstring and comment conventions are documented in docs/contributing/code-style.md. CI runs Ruff; see docs/guides/code-quality.md.

Documentation

Full documentation is hosted at pynydus.readthedocs.io.

See CONTRIBUTING.md for the full development guide.

Status

Early development. APIs and on-disk formats may change between releases.

License

MIT