Quickstart

Get Liminal running locally in a few minutes.

Prerequisites

• Node.js 22+
• npm 10+
• An OpenAI-compatible API key (OpenRouter, OpenAI, etc.)

One-command install (new users)

Linux / macOS / WSL:

curl -fsSL https://vireondynamics.com/install/install.sh | bash

Windows (PowerShell):

irm https://vireondynamics.com/install/install.ps1 | iex

This clones Liminal, runs the setup wizard, verifies the install, and opens the web UI with persona bootstrap. Paths, CI, and flags: Install guide.

Manual install (contributors)

1. Install dependencies

git clone https://github.com/traidy2222/liminal-ai.git
cd liminal-ai
npm install

2. Setup wizard

npm run setup

The wizard writes .env (API key, provider, port), runs npm install / npm run build if needed, and optionally smoke-tests your provider.

Alternatively, copy .env.example at the repository root and set at minimum:

AGENT_API_KEY=your_key_here

Optional overrides in .env: AGENT_API_BASE_URL, AGENT_MODEL, PORT, AGENT_VAULT_PATH, AGENT_WORKSPACE_ROOT.

Product tuning (distill, lazy tools, web timeouts) lives in typed defaults and the Web Settings modal — not in .env. See Configuration basics.

3. Build

If you skipped the wizard, compile core and tools before TUI/web/eval:

npm run build
# or
npm run build -w packages/core
npm run build -w packages/tools

4. Run

# Terminal UI
npm run tui

# Web UI (API + static client on PORT, default 3001)
npm run web

# Web with Vite hot reload (API :3001, client :5173)
npm run web:dev

Or use the CLI:

node scripts/liminal.mjs web --bootstrap --open
node scripts/liminal.mjs tui --bootstrap
npm run doctor

First-run persona bootstrap may appear in web/TUI unless disabled (AGENT_PERSONA_BOOTSTRAP=0). Force re-show: npm run web -- --bootstrap or npm run tui -- --bootstrap.

Smoke test

1. Ask: “List packages under packages/ and summarize each.” — expect real read_file / list_dir paths.
2. Open Settings in web and toggle a non-secret flag (e.g. UI verbosity) — saves to .agent_runtime_prefs.json.
3. After changing packages/core or packages/tools, rebuild and restart the interface.

Next steps

Goal	Read
Install paths & CI	Install
Configure flags	Configuration basics, Environment reference
Persona & vault workflows	Persona bootstrap, Vault briefs
Architecture	Architecture
Problems	Troubleshooting