nestdx 0.1.0

Secure workspaces for AI-assisted development

NestDX

Secure, governed workspaces for AI-assisted development.

NestDX wraps your AI coding tools (Claude Code, Codex, Cursor, HatchDX agents, or any CLI tool) with session tracking, secrets scanning, filesystem policy enforcement, cost tracking, and CI integration — so you can move fast without leaking credentials or breaking boundaries.

Install

# From source
pip install .

# With uv
uv pip install .

Requirements: Python 3.13+, Git

Quick Start

# 1. Initialize a workspace (creates nestdx.yaml + .nestdx/ directory)
nestdx init my-project
nestdx init --template python        # or: typescript, default

# 2. Start a session (snapshots git state, activates file watcher)
nestdx start

# 3. Run a tool within the session
nestdx run claude-code               # named tool adapter
nestdx run codex                     # Codex adapter
nestdx run cursor                    # Cursor (GUI — blocks until you press Enter)
nestdx run hdx-agent                 # HatchDX agent
nestdx run -- pytest -x              # any CLI command via generic adapter

# 4. Stop the session (captures git diff, runs policy checks)
nestdx stop

# 5. Review what happened
nestdx log                           # full session details
nestdx log --cost                    # token/cost breakdown
nestdx audit --ci                    # re-run policy checks (exit 1 on errors)
nestdx sessions                      # list all sessions
nestdx sessions --summary            # aggregated stats
nestdx report --by-tool              # usage report

Tool Setup

NestDX supports five tool adapters out of the box:

Tool	Install	NestDX Command
Claude Code	npm install -g @anthropic-ai/claude-code	nestdx run claude-code
Codex	npm install -g @openai/codex	nestdx run codex
Cursor	cursor.com (GUI)	nestdx run cursor
HatchDX	pip install hatchdx	nestdx run hdx-agent
Any CLI	On PATH	nestdx run -- <command>

Configure tools in nestdx.yaml:

tools:
  claude-code:
    enabled: true
    config:
      model: claude-sonnet-4-5-20250929
  codex:
    enabled: true
    config:
      model: o4-mini
  cursor:
    enabled: true
  hdx-agent:
    enabled: true
    agent_path: ./agents/my-agent    # required for HatchDX

Container Mode

Run tools inside an isolated container with resource limits and network controls:

# Add to nestdx.yaml
environment:
  base: python:3.13-slim
  setup:
    - "pip install -r requirements.txt"
  test_command: "pytest tests/ -v"
  lint_command: "ruff check src/"
  env_file: ".env.nest"
  # volumes:
  #   - "/data:/data:ro"

nestdx start                         # auto-detects container mode
nestdx start --local                 # force local mode
nestdx start --container             # require container mode (fail if no env config)
nestdx start --dry-run               # validate config without starting

Container mode requires Docker, Podman, or nerdctl on PATH.

Network Egress Control

In container mode, restrict outbound network access to specific domains:

policies:
  network:
    allowed_domains:
      - "pypi.org"
      - "registry.npmjs.org"
      - "api.anthropic.com"
    block_all_other_egress: true      # block all other outbound traffic

Network policy is enforced via iptables inside the container. In local mode, NestDX warns that the policy cannot be enforced.

CI Integration

GitHub Actions

Generate a workflow file automatically:

nestdx init --ci                     # creates .github/workflows/nestdx-audit.yaml

Or add to your existing workflow:

- name: Run NestDX audit
  run: |
    nestdx audit --ci \
      --base-ref ${{ github.event.pull_request.base.sha }} \
      --head-ref ${{ github.event.pull_request.head.sha }} \
      --format sarif \
      > nestdx-results.sarif
- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: nestdx-results.sarif

The audit command:

• Diffs files between two git refs
• Scans for secrets and policy violations
• Outputs SARIF, JSON, or Rich (terminal) format
• Exits with code 1 when error-level violations are found

Reporting

nestdx report                        # last 30 days, Rich table
nestdx report --days 7               # last 7 days
nestdx report --by-tool              # breakdown by tool
nestdx report --by-engineer          # breakdown by git author
nestdx report --format json          # JSON output
nestdx report --format csv           # CSV output

Session data is stored as JSON (source of truth) with a SQLite index for fast aggregation queries.

Configuration Reference

Full nestdx.yaml schema:

name: my-project
version: "0.1.0"

# --- Environment (optional — enables container mode) ---
environment:
  base: python:3.13-slim             # base Docker image
  setup:                             # commands to run during image build
    - "pip install -r requirements.txt"
  test_command: "pytest tests/ -v"   # optional: test runner
  lint_command: "ruff check src/"    # optional: linter
  env_file: ".env.nest"             # optional: env vars file (never committed)
  dockerfile: "./Dockerfile.nest"    # optional: custom Dockerfile
  volumes:                           # optional: extra volume mounts
    - "/data:/data:ro"
  cache_dirs:                        # optional: cache directories
    - "~/.cache/uv"
    - "~/.cache/pip"

# --- Tools ---
tools:
  claude-code:
    enabled: true
    config:
      model: claude-sonnet-4-5-20250929
      max_tokens: 8096
  codex:
    enabled: true
    config:
      model: o4-mini
      provider: openai
  cursor:
    enabled: true
  hdx-agent:
    enabled: true
    agent_path: ./agents/my-agent

# --- Policies ---
policies:
  secrets:
    scan_agent_output: true
    scan_commits: true
    block_patterns:                   # regex patterns for secret detection
      - "AWS_SECRET_ACCESS_KEY\\s*=\\s*\\S+"
      - "PRIVATE_KEY"
      - "password\\s*=\\s*\\S+"
      - "Bearer\\s+[A-Za-z0-9\\-._~+/]{20,}"
      - "ghp_[A-Za-z0-9]{36}"
      - "sk-[A-Za-z0-9]{32,}"
    custom_patterns_file: ".nestdx-secrets.yaml"   # optional: extra patterns

  filesystem:
    read_only:                        # files agents must not modify
      - ".env*"
      - "secrets/"
      - ".git/"
      - "*.pem"
      - "*.key"
    no_write:                         # directories agents must not write to
      - "production/"
      - "deploy/"
    allowed_write:                    # explicit write-allow list
      - "src/"
      - "tests/"

  network:
    allowed_domains:                  # egress whitelist (container mode only)
      - "pypi.org"
      - "api.anthropic.com"
    block_all_other_egress: true

  resources:
    max_cpu: "2.0"                   # CPU limit (container mode)
    max_memory: "2g"                 # memory limit (container mode)
    max_session_duration: "4h"       # session timeout

# --- Tracking ---
tracking:
  log_file_changes: true
  log_commands: true
  track_tokens: true                  # parse token usage from tool output
  track_cost: true                    # estimate cost from token usage
  session_dir: ".nestdx/sessions/"
  export_format: "json"

CLI Reference

Command	Description
nestdx init [name]	Initialize workspace (creates nestdx.yaml)
nestdx init --ci	Also generate GitHub Actions workflow
nestdx start	Start a session
nestdx start --dry-run	Validate config without starting
nestdx start --local	Force local mode
nestdx start --container	Require container mode
nestdx start --force	Force-stop stale session before starting
nestdx stop	Stop session, run policy checks
nestdx stop --force	Force-stop a stale session
nestdx run <tool>	Run a named tool adapter
nestdx run -- <cmd>	Run any command via generic adapter
nestdx log	Show last session details
nestdx log --cost	Show token/cost breakdown only
nestdx log -s <id>	Show specific session
nestdx audit	Re-run policy checks on last session
nestdx audit --ci	Exit 1 on error-level violations
nestdx audit --base-ref <sha>	Diff-based audit (no session needed)
nestdx audit --format sarif	SARIF output for GitHub Security tab
nestdx sessions	List all sessions
nestdx sessions --summary	Aggregated stats
nestdx report	Usage report (last 30 days)
nestdx report --by-tool	Breakdown by tool
nestdx report --format json	JSON output

Global flags: --verbose / -v (debug output), --quiet / -q (suppress noise)

How It Works

nestdx start  →  Snapshot git state, start file watcher
                  Optionally: build + start container
                  ↓
nestdx run    →  Launch tool inside governed session
                  Track commands, capture output
                  Real-time secrets scanning (watcher)
                  ↓
nestdx stop   →  Capture git diff (files changed)
                  Run post-session policy checks
                  Record violations, cost data
                  Stop container (if running)
                  ↓
nestdx audit  →  Re-scan for secrets + policy violations
                  CI-ready: exit codes, SARIF output

License

Proprietary. All rights reserved.