5-Minute Quickstart

From zero to a working AI agent in under 5 minutes. This guide walks you through installation, creating an agent, running a conversation, and launching your first mission.

Prerequisites

Tip: If you want to run agents without an API key, install Ollama for free local models.

Step 1: Install Nestor

Run the interactive installer. It will detect your system, prompt for API keys, and configure your environment.

# Install globally
npx nestor-sh install

# Or with pnpm
pnpm dlx nestor-sh install

The installer will:

  1. Create a .nestor/ configuration directory
  2. Ask which LLM providers you want to use
  3. Securely store your API keys
  4. Initialize the SQLite database
  5. Optionally pull the Docker sandbox image

Step 2: Create an Agent

Create your first agent with a name, LLM adapter, and model.

# Create a coding assistant with Claude
npx nestor-sh agent create \
  --name coder \
  --adapter claude \
  --model claude-sonnet-4-6

# Or an OpenAI-based agent
npx nestor-sh agent create \
  --name reviewer \
  --adapter openai \
  --model gpt-4o

# Or a local Ollama agent (free, no API key)
npx nestor-sh agent create \
  --name local-helper \
  --adapter ollama \
  --model llama3.2

Tip: Run npx nestor-sh agent list to see all your configured agents.

Step 3: Launch the Shell

Start an interactive conversation with your agent. The shell gives access to tools, memory, and your codebase.

# Use the default agent
npx nestor-sh shell

# Or specify a specific agent
npx nestor-sh shell --agent coder

# Use a Hat for specialized personas (v3.4.0)
npx nestor-sh shell --hat osint
npx nestor-sh shell --hat security
npx nestor-sh shell --hat researcher

# Enable dry-run mode (preview before execute)
npx nestor-sh shell --dry-run

New in v3.4.0: The --hat flag loads a specialized persona with role-specific tools and instructions. Available hats: coder, researcher, security, writer, osint.

In the shell, try commands like:

Step 4: Launch the Studio

Start the web dashboard to monitor agents, edit workflows, and track costs visually.

# Start the Studio on port 3100
npx nestor-sh start

# Custom port
npx nestor-sh start --port 8080

Open http://localhost:3100 to access the Studio. From there you can:

Step 5: Your First Mission

Missions are Nestor's most powerful feature. Instead of chatting back and forth, give an objective and let sub-agents handle the rest.

# In the shell, just describe your objective
npx nestor-sh shell

> Do an OSINT investigation on John Smith

# Nestor will automatically:
# 1. Create a mission with sub-objectives
# 2. Execute sub-agents in parallel
# 3. Cross-reference findings
# 4. Generate a structured report

# View mission results
npx nestor-sh mission list
npx nestor-sh mission view <id>

Tip: Read the full Missions documentation to learn about decomposition, iteration, and report generation.

Step 6: Use Backpressure Validators

The loop command with --validate runs tests as quality gates. Each iteration must pass before proceeding:

# Loop with backpressure validation (v3.4.0)
npx nestor-sh loop --validate "Build the auth module with JWT"

# Nestor will:
# 1. Code the first iteration
# 2. Run tests as quality gates
# 3. If tests fail, iterate with progressive strictness
# 4. Stop when all tests pass

Step 7: Write and Run Tests

Nestor includes a skill testing framework. Write tests in YAML to validate agent behavior.

# Create a test file
# .nestor/tests/my-agent.test.yaml
name: My Agent Tests
agent: coder
tests:
  - name: should suggest improvements
    prompt: "Review this code: function add(a,b){return a+b}"
    expect:
      output_contains:
        - "type"
      max_iterations: 5

# Run all tests
npx nestor-sh test

# Run with verbose output
npx nestor-sh test --verbose

Next Steps

✎ Edit this page on GitHub · Last updated 2026-04-26