Documentation
Links
npm package
GitHub repo
RLM paper
Developer Docs

# Getting Started

Everything you need to run Agentnetes on your codebase · from a first `npx` command to production agent swarms.

Step 1
Get API key
Free at aistudio.google.com
Step 2
Pull Docker image
`docker pull node:20-alpine`
Step 3
Run on your repo
`npx agentnetes run "goal"`

## Quick Start

No installation required. Point Agentnetes at any git repo in under 2 minutes.

### 1. Get a Google API key

Agentnetes uses Gemini 2.5 Pro (planner) and Gemini 2.5 Flash (workers) by default. Get a free API key from aistudio.google.com. The free tier is sufficient for most tasks.

### 2. Pull the Docker base image

bash

    docker pull node:20-alpine

This is a one-time step. Each agent gets its own container · pulling it now means the first run starts immediately.

### 3. Run on your repo

bash

    # From inside any git repository
    cd your-project
    GOOGLE_API_KEY=your_key npx agentnetes run "add comprehensive test coverage"

### What you will see

    Agentnetes
      Zero to a self-organizing AI agency. On demand.

      Repo:     https://github.com/your-org/your-repo
      Goal:     add comprehensive test coverage
      Sandbox:  cloning from git

      🧠 Tech Lead
        analyzing goal + repo structure

        > find . -name "*.test.ts" -maxdepth 4
        > grep -r "describe\|it(" src/ -l

      + 🔍 Scout          exploring test coverage gaps
      + 🛠  Engineer       implementing missing tests
      + ✅ Tester         verifying test suite passes

      [Scout]    found 12 files with no test coverage
      [Engineer] writing vitest tests for auth module
      + src/auth/auth.test.ts  (typescript)
      [Tester]   all 47 tests passing

      Summary
      ------
      Added 3 test files covering auth, middleware, and utils...

      Done.

Tip:Run `npx agentnetes` with no arguments to see all available commands.

### 3. Install globally (optional)

Skip the `npx` prefix by installing once:

bash

    npm install -g agentnetes

    # Then use anywhere
    GOOGLE_API_KEY=your_key agentnetes run "refactor auth module to use JWT"

### Prerequisites

Node.js 18+Required
Docker any recent version Required for docker sandbox (default)
Google API key free tier works Required · or use AI Gateway
Git repo must have origin remote Required
Note:Pull the Docker base image once to speed up first runs: `docker pull node:20-alpine`

## How it Works

Agentnetes implements the RLM pattern (MIT CSAIL) · context lives in sandboxes, not prompts.

1. You type a goal
A natural-language description of what you want done. No special syntax required.
2. Root agent plans
A Tech Lead agent explores your repo structure and invents a specialist team tailored to the goal. Roles are fully emergent · nothing is hardcoded.
3. Specialists run in parallel
Each specialist gets its own isolated sandbox with the repo cloned inside. They use two tools: search() and execute(). No file contents stuffed into prompts.
4. AutoResearch loop
Agents write code, run tests, observe failures, patch, and repeat · following the write → test → fix loop until the task is done or the step budget is reached.
5. Synthesis
The root agent collects all findings and delivers a final markdown summary of everything built.

### The two-tool strategy

Every agent has exactly two tools · keeping the token footprint under ~1,000 tokens regardless of codebase size:

typescript

    search(pattern, path?, fileGlob?)  // grep -r across the repo
    execute(command)                   // run any shell command in the sandbox

## Local Dev with Docker

Run the full Agentnetes web app locally with real Docker sandboxes · no cloud accounts needed. Each agent gets its own `node:20-alpine` container with the target repo cloned inside.

### 1. Pre-pull the Docker image

Do this once to avoid the image download on your first run:

bash

    docker pull node:20-alpine

### 2. Create .env.local

In the root of the agentnetes repo, create a `.env.local` file:

bash

    # ── Sandbox ───────────────────────────────────────────────────────
    SIMULATION_MODE=false
    SANDBOX_PROVIDER=docker

    # ── Google Gemini · get free key at aistudio.google.com ───────────
    GOOGLE_API_KEY=your_key_here

    # ── Target repo for agents to work on ─────────────────────────────
    DEMO_REPO_URL=https://github.com/expressjs/express

### 3. Start the dev server

bash

    npm run dev

### 4. Open the demo page

Navigate to `http://localhost:3000/demo`. The page defaults to Real mode. Use the Real/Simulation toggle in the header to switch modes. Select a model and submit a goal. Use Gemini 2.5 Flash for faster planning — 2.5 Pro has extended thinking which can take 30-60s. GOOGLE_API_KEY is read from the environment (set in `.env.local` or exported in your shell).

### 5. Watch containers spin up

In a separate terminal, poll Docker every second to see agents appearing and disappearing:

bash

    watch -n 1 docker ps

You will see one container per worker agent. They are automatically removed when the agent finishes.

Tip:For faster iteration, point `DEMO_REPO_URL` at a small repo like `expressjs/express`. Large monorepos (e.g. `vercel/ai`) take 60-90s to clone per container.

### What happens end-to-end

POST /api/chat
Browser sends the goal and selected model to the Next.js API route.
Planner calls Gemini
The Tech Lead agent calls your GOOGLE_API_KEY directly · no gateway.
Worker containers start
One docker run per specialist · node:20-alpine with git + bash installed, repo cloned to /workspace.
Agents execute tools
search() and execute() run bash commands inside /workspace via docker exec.
SSE stream to browser
Events (task-created, terminal, finding, done) stream in real time to the UI.
Containers stop
Each container is removed automatically after its agent completes (--rm flag).

## CLI Reference

### agentnetes run

Run a swarm of agents against the current git repository.

bash

    agentnetes run "<goal>"

    # Examples
    agentnetes run "add TypeScript strict mode and fix all type errors"
    agentnetes run "write unit tests for the auth module"
    agentnetes run "implement rate limiting on all API routes"
    agentnetes run "add OpenTelemetry tracing throughout the app"

Note:Must be run from inside a git repository with a remote `origin`. Agentnetes auto-detects the repo URL.

### agentnetes snapshot create

Pre-warm a Vercel sandbox snapshot of your repo so future runs start in seconds instead of cloning from scratch.

bash

    VERCEL_TOKEN=your_token agentnetes snapshot create

### agentnetes snapshot list

List all available snapshots in your Vercel account.

bash

    VERCEL_TOKEN=your_token agentnetes snapshot list

### agentnetes serve

Start the Agentnetes web UI on your local machine. No source code needed.

bash

    # Start on default port 3000
    npx agentnetes serve

    # Custom port
    npx agentnetes serve --port 8080

Then open http://localhost:3000 in your browser. Set GOOGLE_API_KEY in your environment before starting:

bash

    export GOOGLE_API_KEY=your_key
    npx agentnetes serve

Tip:The web UI has a Real/Simulation toggle. Real mode runs live agents. Simulation mode shows pre-scripted scenarios with no API key needed.

## Web UI (serve)

`agentnetes serve` starts the bundled Next.js web UI directly from the npm package. No cloning the repo or running `npm run dev` required.

### Setting GOOGLE_API_KEY

The API key is read from environment variables only. Set it before starting the server:

bash

    # Option 1: export in your shell session
    export GOOGLE_API_KEY=your_key
    npx agentnetes serve

bash

    # Option 2: add to .env.local in the directory where you run serve
    GOOGLE_API_KEY=your_key

### Settings modal

The Settings modal (gear icon in the header) lets you configure:

Repo URL The git repository agents will clone and work on
Sandbox provider docker | local | vercel | e2b | daytona
Planner model Model used by the root Tech Lead agent
Worker model Model used by specialist agents
GOOGLE_API_KEY status Green check if set, yellow warning with instructions if not
Warning:GOOGLE_API_KEY cannot be entered in the web UI. It must be set as an environment variable or in `.env.local` before starting the server.

### Real vs Simulation toggle

The header has a Real/Simulation toggle. Real is the default and runs live agents against your repo using the Gemini API. Simulation mode plays back pre-scripted scenarios and requires no API key, useful for demos and UI development.

## Sandbox Providers

Each agent runs in its own isolated sandbox with the repo cloned inside. Choose the provider that fits your setup:

Provider Env var Speed Notes
`docker``-`Fast Default. node:20-alpine per agent.
`local``-`Fastest Runs on host machine. No isolation.
`vercel` `VERCEL_TOKEN` Fastest*Firecracker microVMs. Snapshot support.
`e2b` `E2B_API_KEY` Fast Install e2b package separately.
`daytona` `DAYTONA_API_KEY` Fast Install @daytonaio/sdk separately.

### Setting the provider

bash

    # Use Docker (default for local dev)
    SANDBOX_PROVIDER=docker GOOGLE_API_KEY=xxx agentnetes run "goal"

    # Use local (fastest, no isolation)
    SANDBOX_PROVIDER=local GOOGLE_API_KEY=xxx agentnetes run "goal"

    # Use Vercel (requires VERCEL_TOKEN)
    SANDBOX_PROVIDER=vercel VERCEL_TOKEN=xxx GOOGLE_API_KEY=xxx agentnetes run "goal"

Tip:For local development, `docker` is recommended over `local` · it prevents agents from writing to your actual working directory.

## Configuration

All configuration is done via environment variables. No config file needed.

### Full reference

bash

    # ── LLM Provider ─────────────────────────────────────────────────
    GOOGLE_API_KEY=                  # Required · get free at aistudio.google.com

    # ── Sandbox ───────────────────────────────────────────────────────
    SANDBOX_PROVIDER=docker          # docker | local | vercel | e2b | daytona
    VERCEL_TOKEN=                    # Required for vercel sandbox

    # ── Models (optional overrides) ───────────────────────────────────
    PLANNER_MODEL=google/gemini-2.5-pro    # Root Tech Lead model
    WORKER_MODEL=google/gemini-2.5-flash   # Specialist agent model

    # ── Web app / serve only ───────────────────────────────────────────
    SIMULATION_MODE=false            # true = always use simulation
    DEMO_REPO_URL=https://github.com/expressjs/express

## Examples

### Add test coverage

bash

    cd your-node-project
    GOOGLE_API_KEY=xxx npx agentnetes run "add vitest unit tests for all utility functions"

### Fix TypeScript errors

bash

    GOOGLE_API_KEY=xxx npx agentnetes run "enable strict TypeScript and fix all type errors"

### Implement a feature

bash

    GOOGLE_API_KEY=xxx npx agentnetes run "add rate limiting middleware to all Express routes using express-rate-limit"

### Security audit

bash

    GOOGLE_API_KEY=xxx npx agentnetes run "audit the codebase for security vulnerabilities and fix them"

### Add observability

bash

    GOOGLE_API_KEY=xxx npx agentnetes run "add OpenTelemetry tracing to all API routes and database queries"

Tip:Be specific in your goals. Instead of "improve the code", try "add error handling to all async functions in the API layer and log errors with structured JSON".

## Architecture

The core runtime is in `lib/vrlm/` and is completely independent of Next.js · you can embed it in any Node.js application.

### Embedding the runtime

typescript

    import { VrlmRuntime } from 'agentnetes/runtime';
    import { VrlmEventEmitter } from 'agentnetes/events';

    const emitter = new VrlmEventEmitter();
    emitter.on(event => {
      if (event.type === 'finding') console.log(event.data.text);
      if (event.type === 'artifact') console.log('File:', event.data.artifact.filename);
      if (event.type === 'done') console.log('Complete.');
    });

    const runtime = new VrlmRuntime(emitter, {
      repoUrl: 'https://github.com/your-org/your-repo',
      plannerModel: 'google/gemini-2.5-pro',
      workerModel: 'google/gemini-2.5-flash',
      maxWorkers: 4,
      maxStepsPerAgent: 20,
    });

    await runtime.run('add comprehensive test coverage');

### Event types

`task-created` A new agent task was spawned
`task-updated` Agent status text changed
`task-completed` Agent finished successfully
`task-failed` Agent encountered an error
`finding` Agent produced a text observation
`terminal` Agent ran a shell command (tool call)
`artifact` Agent created or modified a file
`collaboration` Agent requested input from another agent
`synthesis` Root agent produced the final summary
`done` All agents finished · run is complete
`error` Fatal runtime error

## Troubleshooting

`Error: not inside a git repository or no remote "origin" found`
Cause:You must run agentnetes from inside a git repo that has a remote named origin.
Fix:cd into your project root and ensure git remote get-url origin returns a URL.
`GOOGLE_API_KEY is not set / no LLM provider configured`
Cause:No API key was provided and no AI Gateway is configured.
Fix:Set GOOGLE_API_KEY=your_key before the command, or add it to a .env file and use dotenv.
`Docker daemon is not running`
Cause:The Docker sandbox (default) requires Docker Desktop or Docker Engine to be running.
Fix:Start Docker Desktop, or switch to local sandbox: SANDBOX_PROVIDER=local
`docker: Cannot connect to the Docker daemon`
Cause:Same as above · Docker is not running or the socket is not accessible.
Fix:Run: open -a Docker (macOS) or sudo systemctl start docker (Linux)
`Fatal: model returned empty response`
Cause:The Gemini API returned nothing · usually a quota or region issue.
Fix:Check your quota at aistudio.google.com. Try WORKER_MODEL=google/gemini-2.0-flash as a fallback.
`Agent exceeded step budget with no result`
Cause:The agent hit the maxStepsPerAgent limit (default: 20) without completing.
Fix:Break the goal into smaller tasks, or increase the budget with WORKER_MAX_STEPS=40.
`GatewayAuthenticationError: Unauthenticated request to AI Gateway`
Cause:AI_GATEWAY_BASE_URL is set in your environment, causing all model calls to route through Vercel AI Gateway instead of Google directly.
Fix:Remove AI_GATEWAY_BASE_URL from your environment or .env.local. Use only GOOGLE_API_KEY for direct Gemini access.
`UI shows nothing after submitting a prompt (empty EventStream)`
Cause:The runtime errored silently. Common causes: invalid API key, model not available, or a missing env var.
Fix:Check the terminal running npm run dev for [chat] error: lines. The UI now shows error messages in the chat panel.
`Gemini 2.5 Pro hangs for 60+ seconds before planning`
Cause:Gemini 2.5 Pro uses extended thinking mode which can take over a minute for complex goals.
Fix:Switch to Gemini 2.5 Flash in the model selector dropdown · it plans in 3-5 seconds.
`Error: web UI not found`
Cause:The standalone web UI was not bundled in this version of the npm package.
Fix:Use npx agentnetes@latest serve to get the latest version with the web UI bundled.
`GOOGLE_API_KEY not set — real agents will not run`
Cause:The API key is read from environment variables only. It cannot be entered in the web UI.
Fix:Run: export GOOGLE_API_KEY=your_key then restart agentnetes serve. Or add it to .env.local.
Tip:Still stuck? Open an issue at github.com/Shashikant86/agentnetes/issues with the error output and your sandbox provider.
Agentnetes · MIT License
Home Demo GitHub npm