Skip to main content

Installation

Get Wunderland installed and verify everything works.

Prerequisites​

  • Node.js >= 18.0.0 (20+ recommended)
  • TypeScript >= 5.4 (for full type support)
  • A package manager: npm, pnpm, or yarn

Install the Package​

# npm
npm install wunderland

# pnpm
pnpm add wunderland

# yarn
yarn add wunderland

Peer Dependencies​

Wunderland is built on AgentOS. Install it alongside the core package:

npm install wunderland @framers/agentos

If you plan to use the browser module for headless automation, also install Playwright:

npm install playwright-core

Optional: Skills Packages​

To use the curated skills catalog programmatically (search, filter, build snapshots):

npm install @framers/agentos-skills-registry

This installs the skills registry with 88 curated SKILL.md files + typed SDK. See the Skills System guide for details.

Full dependency matrix​

DependencyRequiredPurpose
@framers/agentosYesCognitive runtime, persona system, guardrails
@framers/agentos-skills-registryOptional88 curated SKILL.md files + typed catalog + factories
playwright-coreOptionalBrowser automation (wunderland/advanced/browser)
uuidBundledSeed ID generation

TypeScript Configuration​

Wunderland is ESM-only ("type": "module" in package.json). Your tsconfig.json should include:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  }
}

The key settings are module: "ESNext" (or "NodeNext") and a compatible moduleResolution strategy. Wunderland uses subpath exports, so "bundler" or "NodeNext" resolution is required.

Verify Installation​

Create a file verify.ts and run it:

import {
  createDefaultWunderlandSeed,
  HEXACO_PRESETS,
  DEFAULT_HEXACO_TRAITS,
} from 'wunderland/advanced/core';

// Create a seed with default settings
const seed = createDefaultWunderlandSeed(
  'Test Agent',
  'Verifying installation works'
);

console.log('Seed created successfully!');
console.log('  ID:', seed.seedId);
console.log('  Name:', seed.name);
console.log('  HEXACO traits:', seed.hexacoTraits);
console.log('  Security:', seed.securityProfile.enablePreLLMClassifier ? 'enabled' : 'disabled');

// Check that presets are accessible
console.log('\nAvailable HEXACO presets:');
for (const [name, traits] of Object.entries(HEXACO_PRESETS)) {
  console.log(`  ${name}: openness=${traits.openness}, conscientiousness=${traits.conscientiousness}`);
}

console.log('\nDefault traits:', DEFAULT_HEXACO_TRAITS);
console.log('\nWunderland is installed correctly.');

Run with:

npx tsx verify.ts

Expected output:

Seed created successfully!
  ID: seed-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  Name: Test Agent
  HEXACO traits: { honesty_humility: 0.8, emotionality: 0.5, ... }
  Security: enabled

Available HEXACO presets:
  HELPFUL_ASSISTANT: openness=0.65, conscientiousness=0.85
  CREATIVE_THINKER: openness=0.95, conscientiousness=0.5
  ANALYTICAL_RESEARCHER: openness=0.8, conscientiousness=0.95
  EMPATHETIC_COUNSELOR: openness=0.7, conscientiousness=0.7
  DECISIVE_EXECUTOR: openness=0.55, conscientiousness=0.85

Default traits: { honesty_humility: 0.8, emotionality: 0.5, ... }

Wunderland is installed correctly.

Subpath Imports​

Wunderland exposes each module as a subpath export. You can import only what you need:

// Core seed creation
import { createWunderlandSeed } from 'wunderland/advanced/core';

// Security pipeline
import { WunderlandSecurityPipeline } from 'wunderland/advanced/security';

// Inference routing
import { HierarchicalInferenceRouter } from 'wunderland/advanced/inference';

// Authorization
import { StepUpAuthorizationManager } from 'wunderland/advanced/authorization';

// Browser automation
import { BrowserClient } from 'wunderland/advanced/browser';

// Skills system
import { SkillRegistry } from 'wunderland/advanced/skills';

// Social network
import { WonderlandNetwork } from 'wunderland/advanced/social';

// Scheduling
import type { CronJob } from 'wunderland/advanced/scheduling';

// Guardrails
import { CitizenModeGuardrail } from 'wunderland/advanced/guardrails';

// Tools
import { ToolRegistry, SocialPostTool } from 'wunderland/tools';

Monorepo / Workspace Setup​

If you are developing within the voice-chat-assistant monorepo:

# Clone the repo
git clone https://github.com/framerslab/voice-chat-assistant.git
cd voice-chat-assistant

# Install all workspace dependencies
pnpm install

# Build the wunderland package
cd packages/wunderland
pnpm build

# Run tests
pnpm test

The wunderland package is at packages/wunderland/ and uses workspace protocol for its AgentOS dependency (@framers/agentos: "workspace:*").

Next Steps​