wonderlands

Wonderlands is a self-hosted, multi-tenant platform for conversational AI agents. You chat with agents in threads; each turn runs as a background job through a multiagent runtime rather than a single blocking request, so agents can take multiple turns, call tools, and wait on input without tying up the connection.

Core capabilities:

• Agents and conversations — an assistant plus custom agents, each with its own instructions and model, talking in persisted sessions/threads backed by an event-sourced run/job model.
• Tools via MCP code mode — external tools come from Model Context Protocol servers, scoped per agent by tool profiles (e.g. the bundled Firecrawl web-search and filesystem servers). Rather than emitting one tool call at a time, the agent gets a catalog of the available MCP tools and invokes them by writing JavaScript that runs in the sandbox, so it can chain calls, transform results, and use npm packages in a single step.
• Browser sandbox — optional Kernel-backed headless browser for web automation tools.
• Scheduled tasks — run an agent on a cron schedule; each fire starts a normal conversation automatically.
• Garden — publish notes and essays from a workspace vault as a static site.

The backend (apps/server) exposes a versioned HTTP API under /v1 and the frontend (apps/client) is the chat UI; they share typed contracts from packages/contracts.

npm workspaces (apps/*, packages/*):

• apps/client — Svelte + Vite frontend (@wonderlands/client)
• apps/server — Hono + TypeScript backend (@wonderlands/server)
• packages/contracts — shared client/server API contract types (@wonderlands/contracts)
• packages/sandbox-runtime-lo — optional lo sandbox runtime (@wonderlands/sandbox-runtime-lo)

Standalone MCP servers (run with bun, not part of the npm workspaces):

• mcp/web — Firecrawl-backed web search/scrape server
• mcp/files-mcp — filesystem server

Supporting directories:

• setup/ — local bootstrap wizard (npm run setup)
• scripts/ — dev and kernel:up helpers
• docs/ — additional documentation

• recent Node.js
• npm with workspace support

Install dependencies from the repo root:

npm install

Always run workspace commands from the repo root, not from inside individual apps.

For the full local bootstrap flow, run:

npm run setup

The setup wizard handles:

• creating apps/server/.env from .env.example
• creating apps/server/.mcp-servers.json from the example
• prompting for provider API keys (OpenAI, Gemini, OpenRouter)
• configuring Langfuse tracing (optional)
• auto-generating MCP_SECRET_ENCRYPTION_KEY
• defaulting Kernel browser sandbox to enabled (KERNEL_ENABLED=true, local provider)
• installing npm dependencies
• running database migrations and seeding a local account
• storing credentials in .credentials.json (optional)

After setup, start the Kernel browser container with npm run kernel:up (requires Docker).

Skip this section if you ran npm run setup — it covers manual setup and adjusting individual settings afterward.

Create the backend env file if you do not already have one:

cp apps/server/.env.example apps/server/.env

Then set the values you need in apps/server/.env.

Minimum useful setup:

• set OPENAI_API_KEY, GOOGLE_API_KEY, or OPENROUTER_API_KEY (at least one)
• MCP_SECRET_ENCRYPTION_KEY is auto-generated by npm run setup; to generate manually: openssl rand -hex 32
• optionally copy apps/server/.mcp-servers.example.json to apps/server/.mcp-servers.json

Optional lo sandbox runtime in local dev:

npm run build --workspace @wonderlands/sandbox-runtime-lo

Then set absolute paths in apps/server/.env:

SANDBOX_LO_BINARY=/absolute/path/to/lo
SANDBOX_LO_BOOTSTRAP_ENTRY=/absolute/path/to/wonderlands/packages/sandbox-runtime-lo/dist/entry.mjs

Use absolute paths here, not $HOME or $PWD. The server reads literal env values and does not expand shell variables inside .env.

Initialize the local database on a fresh setup:

npm run db:migrate --workspace @wonderlands/server
npm run db:seed --workspace @wonderlands/server

If apps/server/var/05_04_api.sqlite already exists and contains usable data, you can skip the migration and seed step.

Kernel browser support is enabled by default after npm run setup. The server probes the configured Kernel endpoint during startup. If the probe fails, the server still starts normally, but browser tools stay disabled.

Kernel requires Docker. Start the local container:

npm run kernel:up

On first run, that command downloads the pinned kernel/kernel-images source revision into ./.cache/kernel-images/, builds a local Docker image from images/chromium-headful/Dockerfile, and starts docker-compose.kernel.yml. The ref/ folder is reference-only and not required for normal local use.

The setup wizard already sets these env vars. For manual setup, add them to apps/server/.env:

KERNEL_ENABLED=true
KERNEL_PROVIDER=local
KERNEL_CDP_URL=http://127.0.0.1:9222
KERNEL_LOCAL_API_URL=http://127.0.0.1:10001

If the server was already running before npm run kernel:up finished, restart it once. Kernel availability is probed during server startup.

Useful local endpoints after Docker starts:

• CDP: http://127.0.0.1:9222
• Playwright API: http://127.0.0.1:10001
• live view: http://127.0.0.1:8080

Cloud mode uses the hosted API instead:

KERNEL_ENABLED=true
KERNEL_PROVIDER=cloud
KERNEL_API_URL=https://api.kernel.sh
KERNEL_API_KEY=<kernel-api-key>

Advanced local overrides:

• KERNEL_SOURCE_DIR=/abs/path/to/kernel-images to build from an existing local checkout instead of downloading
• KERNEL_IMAGES_REF=<git-sha> to pin a different upstream revision
• KERNEL_REBUILD=true to force a rebuild even when the local image already exists

The client usually works without extra setup in local development because it proxies /v1 to the backend at http://127.0.0.1:3000.

Optional local overrides can go in apps/client/.env.local, for example:

VITE_BACKEND_ORIGIN=http://127.0.0.1:3000
VITE_API_TENANT_ID=your_tenant_id

Start both apps from the repo root:

npm run dev

Default local URLs:

• client: http://127.0.0.1:5173
• server: http://127.0.0.1:3000
• API root: http://127.0.0.1:3000/v1

Start the apps separately:

npm run dev:server
npm run dev:client

Do not commit:

• apps/server/.env
• apps/server/.mcp-servers.json
• .credentials.json
• apps/server/var/
• apps/server/tmp/
• node_modules/
• .cache/

Commit the safe examples instead:

• apps/server/.env.example
• apps/server/.mcp-servers.example.json

If you accidentally exposed a real API key, revoke/rotate it with the provider before pushing publicly.

Run the default fast validation loop from the repo root:

npm run typecheck
npm run lint
npm run test

npm run test runs the fast server, client, Files MCP, and shared MCP suites. Broader integration, timing, subprocess, and race coverage lives in the extended tier:

npm run test:extended

Run the complete release gate before deployment-sensitive changes:

npm run test:release

The release gate runs typechecking, linting, fast and extended tests, standalone MCP typechecks, and the production client build. The production deployment workflow must pass this gate before deployment begins.

Useful package-specific commands:

npm run test:fast --workspace @wonderlands/server
npm run test:extended --workspace @wonderlands/server
npm run test:fast --workspace @wonderlands/client
npm run test:extended --workspace @wonderlands/client
npm run test:mcp
npm run kernel:up
npm run kernel:down

Built by overment.

Released under the MIT License. Copyright (c) 2026 overment.