NaCl

A Fully Autonomous Security Testing Agent System for Autonomous Environment Exploration and Exploitation

English · 简体中文

NaCl Agent is a fully autonomous penetration testing assistant. Just as Claude Code is built for software engineering, NaCl works with you directly in the terminal and autonomously carries out the complete attack chain—from reconnaissance and vulnerability discovery to exploitation, post-exploitation, validation, and reporting—with evidence supporting every conclusion. It is not a coding assistant; it is a penetration testing specialist.

NaCl Agent v1.0.0. The command-line entry point is nacl.

🎯 What It Provides

• Interactive terminal chat with multi-provider model selection and adjustable thinking levels.
• Built-in read, bash, edit, write, grep, find, ls, and skill tools.
• Sessions stored locally and available for continuation, branch switching, forking, cloning, or HTML export.
• Agent Skills, prompt templates, themes, and extensions that can add domain-specific workflows, tools, commands, and UI capabilities.
• Text, JSON, and RPC modes for terminal usage and integration with other processes.
• Runtime data stored inside the project rather than the normal user-home configuration location.

✨ Requirements

Component	Requirement or purpose
Windows / macOS / Linux	Use the provided scripts (install.ps1 / install.sh) for quick deployment; the nacl CLI runs on all three platforms.
Node.js	>= 22.19.0 (the repository's declared minimum).
npm	Installs the root workspace dependencies.
Git for Windows	Recommended on Windows; provides Bash for the LLM-callable bash tool.
Model access	Credentials or an API key for a supported provider.

Check local prerequisites:

node --version
npm --version
git --version
Test-Path -LiteralPath "C:\Program Files\Git\bin\bash.exe"

🚀 Quick Start

Install NaCl Agent with a single command. The installer clones the official repository (HT7-Lab/NaCl), installs dependencies, builds the CLI, and makes the nacl command globally available.

PowerShell (Windows):

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/HT7-Lab/NaCl/main/scripts/install.ps1 | iex"

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/HT7-Lab/NaCl/main/scripts/install.sh | bash

Prerequisites: git, Node.js >= 22.19.0, and npm.

After installation, start NaCl Agent from any directory:

nacl

Review before execution: the one-command installer downloads and executes code from GitHub. If you do not fully trust the source, inspect scripts/install.ps1 or scripts/install.sh before running it.

Common Commands

Goal	Command
Start with an initial request	nacl "Review the current project and explain its layout"
Run one task and exit	nacl -p "Summarize README.md"
Attach a file to the first prompt	nacl @README.md "Review this document"
Continue the latest session	nacl --continue
Choose a previous session	nacl --resume
Start a named session	nacl --name "authentication review"
Use a specific provider and model	nacl --provider openai --model gpt-4o-mini "Explain this code"
Restrict the Agent to read-only tools	nacl --tools read,grep,find,ls -p "Review this project"
Disable all Agent tools	nacl --no-tools
Disable startup network operations	nacl --offline

@path attaches a file to the first message. In the interactive editor, type @ to search project files.

The full command line also supports --mode json, --mode rpc, explicit session paths, model cycling, thinking levels, custom resources, and per-run tool exclusions.

An explicit --tools list only limits which tools the Agent may call. It does not sandbox the process, network, or operating-system account. Use a VM, container, or restricted account when OS-level isolation is required.

Sessions, Configuration, and Resources

The included launcher configures the following runtime locations:

~/.nacl/agent/                  # NaCl runtime data (stored under the project root in portable mode)
~/.nacl/agent/sessions/         # Session JSONL files
~/.nacl/agent/skills/           # User-installed NaCl Skills
~/.nacl/agent/settings.json     # Local settings
~/.nacl/agent/models.json       # Custom provider/model definitions

Authentication data is also local runtime data and must not be committed, included in public archives, or shared with exported sessions.

The environment variables NACL_CODING_AGENT_DIR and NACL_CODING_AGENT_SESSION_DIR can override the default runtime and session locations; --session-dir overrides the session directory for a single invocation.

Skills are on-demand instruction packages. The local build discovers the NaCl Skill directory, the user-level ~/.agents/skills/ directory, and project-level .nacl/skills/ or .agents/skills/ directories.

Use /skill:<name> in the terminal UI, or allow the Agent to load a matching Skill automatically. Restart NaCl or use /reload after changing locally discovered resources.

Extensions, prompt templates, and themes can change Agent behavior. From this source checkout, use nacl install, nacl remove, nacl list, nacl config, and nacl update to manage resources. Self-update is disabled in this local build. Review third-party source code and pin versions before installation.

Development and Validation

From E:\nacl, use the root workspace scripts:

npm run build          # May refresh model data, then build the workspaces
npm run build:offline  # Build using existing local model data
npm run check          # Format, lint, type-check, and validate the repository

npm run build may refresh model data and therefore may require network access.

For offline or reproducible builds, use npm run build:offline after the required model data is already available locally.

When changing application code, follow the repository's AGENTS.md. In particular, run targeted tests appropriate to the change and avoid the full test suite unless the environment and task explicitly require it.

📚 Repository Layout

Path	Responsibility
packages/coding-agent	NaCl terminal CLI, interactive UI, built-in tools, resource loading, and session handling.
packages/agent	General Agent runtime, transport abstraction, state, and attachments.
packages/ai	Provider-neutral LLM API, model discovery, and provider configuration.
packages/tui	Differential-rendering terminal UI library.
packages/client, packages/protocol, packages/server	Remote-session client, framed CBOR protocol, and experimental server components.
packages/session-backends/sqlite-node	Node.js SQLite session backend.
packages/telemetry	Provider-neutral telemetry contracts and typed schemas.
packages/evals	Evaluation workspace.
nacl.cmd, nacl.ps1, nacl-run.ps1	Windows source launchers and portable runtime setup.

🛠️ Troubleshooting

• The Agent cannot execute shell commands: install Git for Windows (git on macOS/Linux), or configure a valid Bash executable in the local Agent settings.
• No model is available: configure a provider with /login, or set the correct provider key in the current process environment, then run --list-models.
• Do not want a session saved: add --no-session.
• Need to stop ongoing work: press Escape or Ctrl+C in the terminal UI.

📝 Technical Report

[Updating]

🤝 Team & Support

Hokago Tea Time Lab

Hailin Zheng

Shibin Deng

Qingyi Huang

---

⚡ Acknowledgments and Feedback

Thanks to all contributors and reviewers. If you have suggestions, spot an error, or want to share field experience, open an Issue. For collaboration inquiries, email iszhenghailin@gmail.com.

📜 License

Copyright (c) 2026 Hokago Tea Time Lab.

Licensed under the MIT License. See LICENSE.