NaCl：A Natural Cyber Exploitation System which is Fully Autonomous and Intelligent.

English · 简体中文 · 中文使用手册

NaCl Agent is a local AI security workbench built on the Arena coding-agent runtime. It combines a terminal agent, a local Web GUI, multi-provider model access, persistent sessions, tool execution, and Agent Skills into one source checkout.

It is intended for authorized security research, CTF workflows, code review, security debugging, and local automation. NaCl can read and edit files and run commands with the permissions of the user who starts it. Use it only in trusted projects or inside an isolation boundary you control.

🎯 What It Provides

• Terminal agent: interactive chat, one-shot print mode, JSON event mode, RPC mode, session resume, session branching, compaction, file references, and slash commands.
• Local Web GUI: browser-based task console with real session list, task graph, node details, realtime logs, Tools view, Skills view, and a unified chat input for creating or continuing sessions.
• Multi-provider LLM runtime: OpenAI, OpenAI Codex, Anthropic, Google Gemini, Google Vertex, DeepSeek, Mistral, Groq, xAI, OpenRouter, Vercel AI Gateway, Amazon Bedrock, Cloudflare, GitHub Copilot, local/OpenAI-compatible endpoints, and other built-in providers.
• Built-in tools: read, write, edit, bash, grep, find, ls, and skill.
• Skills and extensions: loads Agent Skills, prompt templates, themes, and TypeScript extensions from global and project-local resource directories.
• Portable runtime state: the private NaCl build stores default configuration, credentials, sessions, skills, and tool data under this project instead of a global user directory.
• Security workbench assets: the repository includes optional security-oriented skills, POC templates, references, and tool-library integration points under patches/ and .nacl/agent when provisioned.

✨ Current Behavior

This checkout is configured as a private NaCl fork:

• Application command name: nacl.
• Display name: NaCl Agent.
• Runtime config directory: .nacl/agent.
• Default mode: full local access.
• Tool approval prompts: disabled.
• Self-update: disabled for the private fork; extension/model catalog updates are still available.
• Web service bind address: 127.0.0.1 only.

🚀 Usage

1. Install

Required: Node.js >= 22.19.0, npm, PowerShell on Windows, and Git for Windows if you want the shell tool to use Git Bash.

Set-Location -LiteralPath "<path-to-NaCl-Agent>"
npm ci --ignore-scripts

2. Configure a model

Start NaCl once and configure credentials in the terminal UI:

.\nacl.cmd

Then run:

/login
/model

You can also set provider environment variables before starting:

$env:OPENAI_API_KEY = "..."
$env:ANTHROPIC_API_KEY = "..."
$env:DEEPSEEK_API_KEY = "..."
$env:GEMINI_API_KEY = "..."

3. Choose an entry point

Goal	Command
Open the terminal agent	.\nacl.cmd
Run one prompt and exit	.\nacl.cmd -p "Summarize this repository."
Start with a prompt	.\nacl.cmd "Inspect this project and explain how to run it."
Attach a file to the first prompt	.\nacl.cmd @README.md "Review this document."
Open the Web GUI	.\nacl-web-gui.cmd
Run the Web server visibly	.\nacl-web.cmd
Run from a Unix-like shell	./pi-test.sh

The Web GUI opens http://127.0.0.1:8088/. Change the port before launch if needed:

$env:NACL_WEB_PORT = "8090"
.\nacl-web-gui.cmd

Health check:

http://127.0.0.1:8088/api/health

4. Common workflows

# Review a project without editing files
.\nacl.cmd --tools read,grep,find,ls -p "Review this repository for security issues."

# Continue the latest saved session
.\nacl.cmd --continue

# Pick a saved session
.\nacl.cmd --resume

# Use a specific model and reasoning level
.\nacl.cmd --model deepseek/deepseek-v4-pro --thinking high

# List available models
.\nacl.cmd --list-models

In the Web GUI:

1. Click New Session, type a prompt, and send it to create a real NaCl session.
2. Select an existing session on the left, then use the same chat box to continue it.
3. Use Stop to cancel a running task and Refresh to reload session state.
4. Archiving a finished session moves its JSONL file to .nacl/agent/sessions/.trash.

5. Useful interactive commands

Command	Purpose
/login	Configure provider credentials.
/model	Select the active model.
/settings	Change model, thinking level, theme, and runtime options.
/new	Start a new session.
/resume	Pick a saved session.
/session	Show current session metadata.
/tree	View and switch session branches.
/compact	Compress older context.
/reload	Reload settings, Skills, prompts, themes, and extensions.

Run .\nacl.cmd --help for the complete CLI reference.

Runtime Data Layout

NaCl's portable runtime data is created on demand:

.nacl/agent/
  auth.json          # stored OAuth/API-key credentials
  settings.json      # global NaCl settings for this checkout
  models.json        # optional custom model/provider definitions
  models-store.json  # cached model catalog data
  sessions/          # JSONL session files
  skills/            # user/runtime Skills
  prompts/           # prompt templates
  themes/            # custom themes
  extensions/        # local TypeScript extensions
  tool-library/      # optional external tool catalog

Project-local resources are loaded from the current working directory:

.nacl/settings.json
.nacl/skills/
.nacl/prompts/
.nacl/themes/
.nacl/extensions/
.agents/skills/
AGENTS.md
CLAUDE.md

In this full-access fork, project resources are trusted automatically. Review them before running NaCl in untrusted repositories.

📚 Getting Started Guides

Path	Purpose
nacl.cmd, nacl.ps1	Windows CLI launchers for the source checkout.
nacl-web.cmd, nacl-web.ps1	Visible local Web service launcher.
nacl-web-gui.cmd, nacl-web-gui.ps1	One-click GUI launcher.
pi-test.sh, pi-test.ps1	Source-mode CLI runner around tsx.
frontend/	Static browser UI for the local task console.
web-ui/server.mjs	Local HTTP/SSE adapter for sessions, tools, skills, and runtime metadata.
packages/coding-agent/	NaCl CLI, session loop, tools, modes, settings, Skills, extensions, and SDK exports.
packages/ai/	Unified LLM provider runtime, model catalogs, auth resolution, streaming, tools, usage, and image support.
packages/agent/	General agent core used by the coding agent.
packages/tui/	Terminal UI framework used by interactive mode.
packages/protocol/	Transport-neutral CBOR protocol schemas.
packages/client/	Transport-neutral remote session client.
packages/server/	Experimental remote session server primitives.
packages/session-backends/sqlite-node/	SQLite-backed session storage package.
packages/evals/	Model-backed behavioral eval harnesses.
packages/telemetry/	Typed telemetry contracts and schema utilities.
patches/vendors/vibe-pentest/	Optional security skill, reference, and POC assets.
assets/	README and brand images.

🛠️ Development

Install once:

npm ci --ignore-scripts

Main workspace commands:

npm run check
.\test.sh
npm run build

Repository policy expects npm run check after code changes. Documentation-only changes do not require the full check unless you want an additional sanity pass.

Testing guidance:

• Use .\test.sh for non-e2e workspace tests.
• Run package-specific tests when you changed a package in isolation.
• Avoid the full Vitest suite directly unless you know e2e provider environment variables are not present.
• Do not run real provider API calls in coding-agent suite tests.

🏗️ Security Model

NaCl Agent is a local agent with the permissions of the launching user. The bash, write, and edit tools can change files and execute local commands. Skills and extensions can also influence behavior, and TypeScript extensions execute code.

Practical guidance:

• Use NaCl only for systems and targets you own or are authorized to assess.
• Run untrusted work inside a VM, container, throwaway checkout, or restricted OS account.
• Review AGENTS.md, .nacl/, .agents/, Skills, extensions, and third-party packages before trusting a project.
• Keep secrets out of prompts and repository files.
• Keep the Web GUI bound to 127.0.0.1; do not expose it on a public network.

See SECURITY.md for the upstream Arena security boundary.

📖 Documentation

• Chinese user manual
• NaCl implementation notes
• Web GUI notes
• Coding agent reference
• Provider runtime reference
• Contributing
• Security policy

📝 Technical Report

The technical report links are not published in this checkout yet.

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