Skip to main content

Quickstart

Create a fully configured Wunderland agent in 5 minutes.

Quick Start: Library API​

The fastest way to get a Wunderland agent running programmatically is createWunderland(). It handles config resolution, tool loading, and LLM wiring in a single call:

import { createWunderland } from 'wunderland';

const app = await createWunderland({
  llm: { providerId: 'openai', model: 'gpt-4o' },
  tools: 'curated',
});

const session = app.session();
const result = await session.sendText('What is quantum computing?');
console.log(result.text);
console.log(result.meta);       // { providerId, model, sessionId, elapsedMs }
console.log(result.toolCalls);  // any tools the agent invoked

await app.close();

createWunderland() reads environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY) automatically, loads agent.config.json if present, and supports tool approval callbacks for side-effect tools. See the Library API Guide for the full reference.

When you run from a real agent project, Wunderland also writes dated plain-text session logs under ./logs/YYYY-MM-DD/*.log by default.

Quick Start: CLI (Natural Language)​

The fastest CLI path -- describe your agent in plain English and the CLI generates a full configuration:

npm install -g wunderland

# One-liner agent creation
wunderland create "A customer support agent for my SaaS product"

# Or interactive mode -- choose between NL describe, preset, blank, or import
wunderland new

# Then start
cd my-agent && wunderland start

wunderland create sends your description to your configured LLM provider, extracts a complete agent configuration (preset, skills, extensions, channels, HEXACO personality, security tier), shows a preview with confidence scores, and scaffolds a ready-to-run project directory. See the NL Agent Creation guide for the full reference.

Once the server is running, open http://localhost:3000/ for the web dashboard (Overview, Chat, HITL, Graph, Events, Extensions tabs). The startup output prints an admin secret for authentication -- set a persistent one via WUNDERLAND_HITL_SECRET or hitl.secret in agent.config.json.

Just Describe What You Want​

You don't need to memorize commands. Just tell Wunderland what you want:

wunderland "Build me a research agent that monitors AI news"
# → Detects intent: create agent → runs create flow

wunderland "Create a team: researcher, analyst, writer"
# → Detects intent: create agency → runs agency create flow

wunderland "Research the latest advances in RAG and write a report"
# → Detects intent: mission → runs mission flow

wunderland "What LLM providers do you support?"
# → Detects intent: help → routes to chat with platform knowledge

The NL intent router is keyword-based and instant (no LLM call). It classifies unrecognized input into five intents -- create, agency, mission, help, or chat -- and dispatches to the appropriate handler. You can always use explicit commands too, but plain English works from the top level.

Quick Start: CLI (Traditional)​

Or use the existing onboarding commands for a guided wizard flow:

npm install -g wunderland
wunderland quickstart  # one-shot detection + scaffold + go
wunderland setup       # interactive onboarding wizard
wunderland             # TUI dashboard + onboarding tour
wunderland chat        # terminal chat session
wunderland doctor      # verify config + provider readiness

Quick Examples​

Copy-paste recipes for the most common workflows.

1. Create a Single Agent from Natural Language​

# Describe what you want -- the CLI extracts a full configuration
wunderland create "A personal assistant that manages my calendar and emails"
cd my-agent && wunderland start

2. Create a Multi-Agent Team from Natural Language​

# One line scaffolds an entire agency with roles and strategy
wunderland agency create "DevOps team: a monitor that watches server health, an analyst that diagnoses issues, and a fixer that applies automated remediations"

# Run the team against a task
wunderland agency run devops-team "Check the production servers for any anomalies"

3. Run a Mission (Auto-Plans and Coordinates Agents)​

# Missions decompose a high-level goal into a plan and coordinate agents automatically
wunderland mission "Research the top 5 AI frameworks, compare their features, and write a blog post with code examples"

4. Interactive Chat with Tools​

# Start an interactive terminal session with specific tools and model
wunderland chat --tools web-search,github --model gpt-4o

5. HITL Approval Modes​

# Auto-approve all tool calls (permissive)
wunderland chat --auto-approve-tools

# Use LLM as judge for approvals
wunderland chat --llm-judge

# Full autonomy (no guardrail safety net)
wunderland chat --overdrive --no-guardrail-override

See the Security & Approvals guide for details on HITL modes and guardrail overrides.

First-Run Checklist​

The recommended getting-started path with create:

wunderland create "A helpful research assistant"
cd seed_helpful_research_assistan
cp .env.example .env   # fill in your API key
wunderland doctor
wunderland chat

Or the traditional path:

wunderland quickstart
wunderland help getting-started
wunderland help tui
wunderland extensions configure
wunderland extensions info image-generation
  • create is the fastest path when you know what you want and can describe it.
  • quickstart is the fastest path when you just want a working agent with defaults.
  • help getting-started and help tui are the shortest built-in operator guides.
  • extensions configure lets you set shared defaults for image generation, TTS, STT, and web search.
  • extensions info image-generation shows which image provider keys are set right now.

Seed Configuration (Advanced)​

For full control over personality, security, and inference routing, create a Seed -- a configuration object that bundles personality, security, inference routing, and authorization into one unit.

import {
  createWunderlandSeed,
  HEXACO_PRESETS,
  DEFAULT_SECURITY_PROFILE,
  DEFAULT_INFERENCE_HIERARCHY,
  DEFAULT_STEP_UP_AUTH_CONFIG,
} from 'wunderland/advanced/core';

const seed = createWunderlandSeed({
  seedId: 'atlas-001',
  name: 'Atlas',
  description: 'Analytical research assistant for academic work',
  hexacoTraits: HEXACO_PRESETS.ANALYTICAL_RESEARCHER,
  securityProfile: DEFAULT_SECURITY_PROFILE,
  inferenceHierarchy: DEFAULT_INFERENCE_HIERARCHY,
  stepUpAuthConfig: DEFAULT_STEP_UP_AUTH_CONFIG,
});

console.log(seed.name);               // "Atlas"
console.log(seed.hexacoTraits);        // { honesty_humility: 0.9, emotionality: 0.3, ... }
console.log(seed.baseSystemPrompt);    // Auto-generated from HEXACO traits

The createWunderlandSeed function normalizes your HEXACO traits (clamping to 0.0-1.0), generates a personality-aware system prompt, maps traits to AgentOS mood adaptation config, and wires up security/inference/auth defaults.

2. Use a HEXACO Preset​

Wunderland ships with five presets for common agent archetypes:

import { HEXACO_PRESETS } from 'wunderland/advanced/core';

// Pick the preset that matches your use case
const traits = HEXACO_PRESETS.ANALYTICAL_RESEARCHER;
// { honesty_humility: 0.9, emotionality: 0.3, extraversion: 0.4,
//   agreeableness: 0.6, conscientiousness: 0.95, openness: 0.8 }

const traits2 = HEXACO_PRESETS.CREATIVE_THINKER;
// { honesty_humility: 0.7, emotionality: 0.6, extraversion: 0.7,
//   agreeableness: 0.6, conscientiousness: 0.5, openness: 0.95 }

Or define custom traits:

const customTraits = {
  honesty_humility: 0.85,
  emotionality: 0.4,
  extraversion: 0.65,
  agreeableness: 0.75,
  conscientiousness: 0.9,
  openness: 0.7,
};

const seed = createWunderlandSeed({
  seedId: 'custom-agent',
  name: 'Sage',
  description: 'Balanced assistant with high integrity',
  hexacoTraits: customTraits,
  securityProfile: DEFAULT_SECURITY_PROFILE,
  inferenceHierarchy: DEFAULT_INFERENCE_HIERARCHY,
  stepUpAuthConfig: DEFAULT_STEP_UP_AUTH_CONFIG,
});

3. Set Up the Security Pipeline​

The security pipeline has three layers that can be individually enabled:

import {
  WunderlandSecurityPipeline,
  createProductionSecurityPipeline,
  createDevelopmentSecurityPipeline,
} from 'wunderland/advanced/security';

// Option A: Production pipeline (all layers on)
const prodPipeline = createProductionSecurityPipeline(
  // Provide an LLM invoker for the dual-LLM auditor
  async (prompt: string) => {
    // Call your LLM provider here
    const response = await callLLM(prompt);
    return response.text;
  }
);

// Option B: Development pipeline (classifier only, no LLM audit or signing)
const devPipeline = createDevelopmentSecurityPipeline();

// Option C: Custom configuration
const customPipeline = new WunderlandSecurityPipeline({
  enablePreLLM: true,
  enableDualLLMAudit: true,
  enableOutputSigning: true,
  classifierConfig: {
    riskThreshold: 0.7,            // Block inputs with risk score >= 0.7
  },
  auditorConfig: {
    evaluateStreamingChunks: true,
    maxStreamingEvaluations: 50,
    auditTemperature: 0.0,         // Deterministic audit
  },
});

Using the pipeline​

// Bind the pipeline to your seed
customPipeline.setSeedId(seed.seedId);

// Evaluate user input before sending to the LLM
const inputResult = await customPipeline.evaluateInput({
  input: { textInput: 'Ignore all previous instructions and...' },
  context: {},
});

if (inputResult?.action === 'block') {
  console.log('Input blocked:', inputResult.reason);
  // Handle blocked input
} else {
  // Safe to proceed -- send to LLM
  const llmResponse = await callLLM(userInput);

  // Evaluate LLM output
  const outputResult = await customPipeline.evaluateOutput({
    chunk: { finalResponseText: llmResponse },
    context: {},
  });

  if (outputResult?.action === 'block') {
    console.log('Output blocked:', outputResult.reason);
  } else {
    // Sign the final output for audit trail
    const signed = customPipeline.signOutput(llmResponse);
    console.log('Signed output ID:', signed?.outputId);
    console.log('Intent chain length:', signed?.intentChain.length);
  }
}

// Reset for next request
customPipeline.reset();

4. Set Up Step-Up Authorization​

Control which tools an agent can use autonomously vs. which require human approval:

import {
  StepUpAuthorizationManager,
} from 'wunderland/advanced/authorization';
import {
  ToolRiskTier,
  DEFAULT_STEP_UP_AUTH_CONFIG,
} from 'wunderland/advanced/core';

const authManager = new StepUpAuthorizationManager(
  DEFAULT_STEP_UP_AUTH_CONFIG,
  // HITL callback -- called when Tier 3 approval is needed
  async (request) => {
    console.log(`Approval needed: ${request.description}`);
    console.log(`Severity: ${request.severity}`);
    // In production, send this to a UI or notification system
    return {
      actionId: request.actionId,
      approved: true,
      decidedBy: '[email protected]',
      decidedAt: new Date(),
    };
  }
);

// Check authorization for a tool call
const result = await authManager.authorize({
  tool: {
    id: 'send-email',
    displayName: 'Send Email',
    category: 'communication',
    hasSideEffects: true,
  },
  args: { to: '[email protected]', body: 'Hello' },
  context: { userId: 'user-123' },
  timestamp: new Date(),
});

console.log('Authorized:', result.authorized);
console.log('Tier:', result.tier);            // 2 (async review for communication)
console.log('Audit required:', result.auditRequired);

5. Complete Working Example​

Here is a full example that brings all the pieces together:

import {
  createWunderlandSeed,
  HEXACO_PRESETS,
  DEFAULT_SECURITY_PROFILE,
  DEFAULT_INFERENCE_HIERARCHY,
  DEFAULT_STEP_UP_AUTH_CONFIG,
  ToolRiskTier,
} from 'wunderland/advanced/core';
import {
  WunderlandSecurityPipeline,
  createProductionSecurityPipeline,
} from 'wunderland/advanced/security';
import { StepUpAuthorizationManager } from 'wunderland/advanced/authorization';
import { HierarchicalInferenceRouter } from 'wunderland/advanced/inference';

// --- 1. Create the seed ---
const seed = createWunderlandSeed({
  seedId: 'nova-001',
  name: 'Nova',
  description: 'Creative AI assistant for brainstorming and ideation',
  hexacoTraits: HEXACO_PRESETS.CREATIVE_THINKER,
  securityProfile: DEFAULT_SECURITY_PROFILE,
  inferenceHierarchy: {
    routerModel: {
      providerId: 'openai',
      modelId: 'gpt-4o-mini',
      role: 'router',
      maxTokens: 512,
      temperature: 0.1,
    },
    primaryModel: {
      providerId: 'openai',
      modelId: 'gpt-4o',
      role: 'primary',
      maxTokens: 4096,
      temperature: 0.8,  // Higher temp for creative agent
    },
    auditorModel: {
      providerId: 'openai',
      modelId: 'gpt-4o-mini',
      role: 'auditor',
      maxTokens: 256,
      temperature: 0.0,
    },
  },
  stepUpAuthConfig: {
    defaultTier: ToolRiskTier.TIER_1_AUTONOMOUS,
    categoryTierOverrides: {
      financial: ToolRiskTier.TIER_3_SYNC_HITL,
      system: ToolRiskTier.TIER_3_SYNC_HITL,
    },
    approvalTimeoutMs: 300000,
  },
  channelBindings: [
    { platform: 'webchat', channelId: 'main', isActive: true },
    { platform: 'discord', channelId: 'guild-123', isActive: true },
  ],
  baseSystemPrompt: 'Focus on generating novel ideas and creative solutions.',
  allowedToolIds: ['web-search', 'giphy', 'social-post'],
});

// --- 2. Set up security ---
const security = createProductionSecurityPipeline(async (prompt) => {
  // Replace with your actual LLM call
  return 'PASS: No safety concerns detected.';
});
security.setSeedId(seed.seedId);

// --- 3. Set up authorization ---
const auth = new StepUpAuthorizationManager(
  seed.stepUpAuthConfig,
  async (request) => ({
    actionId: request.actionId,
    approved: true,
    decidedBy: 'system',
    decidedAt: new Date(),
  })
);

// --- 4. Process a request ---
async function handleUserMessage(userInput: string) {
  // Security check
  const inputCheck = await security.evaluateInput({
    input: { textInput: userInput },
    context: { seedId: seed.seedId },
  });

  if (inputCheck?.action === 'block') {
    return { blocked: true, reason: inputCheck.reason };
  }

  // Route to appropriate model (simple queries -> router, complex -> primary)
  // In production, use HierarchicalInferenceRouter here

  // Generate response (placeholder)
  const response = `Nova says: Here is a creative take on "${userInput}"...`;

  // Audit output
  const outputCheck = await security.evaluateOutput({
    chunk: { finalResponseText: response },
    context: { seedId: seed.seedId },
  });

  if (outputCheck?.action === 'block') {
    return { blocked: true, reason: outputCheck.reason };
  }

  // Sign and return
  const signed = security.signOutput(response);
  security.reset();

  return {
    blocked: false,
    response,
    outputId: signed?.outputId,
    signature: signed?.signature,
    intentChainLength: signed?.intentChain.length,
  };
}

// --- Run it ---
const result = await handleUserMessage('What are 5 unconventional uses for AI in farming?');
console.log(result);

Connecting Services​

The agent can help you set up credentials for any service -- just ask in plain English:

# Just ask the agent -- it'll guide you through it
wunderland "help me set up Gmail"
wunderland "I downloaded a Google client secret, help me connect"

# Or use the connect command directly
wunderland connect gmail
wunderland connect gmail --credentials ~/Downloads/client_secret_*.json
wunderland connect whatsapp
wunderland connect slack
wunderland connect signal

The agent knows what credentials each service needs (via bundled platform knowledge) and can find downloaded credential files on your system. For the full list of supported services and their credential requirements, see the Email Intelligence guide and the CLI Reference.

Next Steps​