noumen — coding agents are products. This is the library.

noumen is the agent runtime you npm install — the missing layer between LLMs and computers, with pluggable providers and virtual infrastructure.

The agent runtime you npm install. noumen gives you the full agentic loop — tool execution, file editing, shell commands, context compaction, and session management — with sandboxed virtual infrastructure that isolates your agent from the host machine. Built for coding agents, ready for any agent that uses a computer. Any provider, any sandbox backend, one package.

Install

One-line install

noumen is published on npm and works with any Node.js package manager.

pnpm add noumen

Quick start

import { LocalAgent } from "noumen/local";

const agent = LocalAgent({ provider: "anthropic", cwd: "." });

for await (const event of agent.run("Add a health-check endpoint to server.ts")) {
  if (event.type === "text_delta") process.stdout.write(event.text);
}

LocalAgent is a convenience factory on the noumen/local subpath that constructs an Agent wired to a LocalSandbox (OS-level sandboxing). For raw host access with no isolation, use UnsandboxedAgent from noumen/unsandboxed. For remote sandboxes or full control, construct an Agent directly — see Virtual Infrastructure for every backend.

Key features

Swap models in one line

OpenAI, Anthropic, Google Gemini, OpenRouter, AWS Bedrock, Google Vertex AI, and Ollama. Same streaming interface, same tool dispatch. Cloud or local.

Sandboxed by default

All tool I/O routes through a Sandbox — the isolation boundary. Seven built-in backends: LocalSandbox (OS-level), UnsandboxedLocal, sprites.dev containers, Docker, E2B cloud, Freestyle VMs, and SSH remote hosts. Remote backends auto-provision on first use and reconnect on session resume. Or implement your own.

Read, write, edit, execute

ReadFile, WriteFile, EditFile, Bash, Glob, Grep, WebFetch, NotebookEdit, AskUser — nine tools for any agent that interacts with a computer.

Connect to anything

Client and server support for Model Context Protocol. Expose external tools and resources seamlessly.

Teach your agent

Inject markdown instructions into the system prompt. Load SKILL.md files from the filesystem.

Embed anywhere

Use in-process, expose over HTTP/SSE or WebSocket, or integrate into Next.js, Electron, and VS Code extensions. Built as a library, not just a CLI.

18 hook events

Intercept tool calls, session lifecycle, permissions, file writes, model switches, retry, compaction, and memory extraction.

CLI included

Run npx noumen to start an interactive session with any provider. One-shot mode, JSONL output, session resume — all from the terminal.

Project context

Drop a NOUMEN.md or CLAUDE.md in your repo and the agent loads project instructions automatically. Hierarchical: managed, user, project, local.

Resume, compact, persist

JSONL-based conversation storage with automatic compaction and resume support.

Next steps

Getting Started

Install, configure, and run your first agent

Embedding

Integrate noumen into your app — in-process, HTTP, WebSocket, or framework-specific

Providers

Configure OpenAI, Anthropic, Gemini, OpenRouter, Bedrock, Vertex, or Ollama

Tools

Built-in tools and custom tool authoring

Hooks

18 events to intercept tool calls, sessions, permissions, file writes, and more

Stream Events

All event types emitted during agent runs

Introduction