Installation

Requirements

• Node.js ≥ 20 — Lookspan ships as an npm package and runs on the Node runtime.
• That’s it. Storage is a local SQLite file; nothing else to install.

Run with npx (recommended)

The fastest path is to run the CLI directly — no global install, no cloud:

npx lookspan              # → http://127.0.0.1:3100

The first run downloads the lookspan package and starts the server. Add --open to launch the dashboard in your browser automatically:

npx lookspan --open

Global install

If you prefer a persistent command:

npm install -g lookspan
lookspan

One-click desktop launcher

Once Lookspan is installed globally, it can add itself to your desktop so you open it the way you open anything else — by clicking an icon:

lookspan install-desktop

Platform	What it creates	Icon
Windows	Lookspan.lnk on the Desktop and in the Start Menu (starts minimized)	yes
macOS	~/Applications/Lookspan.app	system default
Linux	~/.local/share/applications/lookspan.desktop (appears in your app menu)	yes

The Windows and Linux entries use the Lookspan mark, generated from the same SVG the dashboard uses as its favicon (npm run icons). macOS needs an .icns bundle, which is not built yet, so the .app shows the system default.

Clicking it starts the server and opens the dashboard — no terminal involved.

Any options you pass are baked into the launcher, so it always starts the way you want:

lookspan install-desktop --port 3200 --retention 7d

Those options are validated before anything is written, so a typo fails now rather than producing an icon that does nothing when clicked.

Remove it with:

lookspan uninstall-desktop

Needs a real install

install-desktop refuses to run from the npx cache. npm is free to delete that cache, which would leave you with a shortcut pointing at nothing — install with npm install -g lookspan first.

Where data lives

By default Lookspan stores everything in a single SQLite file at ~/.lookspan/lookspan.db, created on first run. Override it with --db / LOOKSPAN_DB. A postgres://… URL connects to the external PostgreSQL server through the Postgres driver, so its data survives Lookspan restarts according to the server’s durability policy. See the configuration reference.

SDK packages

Instrumentation lives in separate, installable packages so your agent project only pulls in what it needs:

Package	Install	Purpose
@lookspan/openai	npm install @lookspan/openai	Wrap the OpenAI client
@lookspan/anthropic	npm install @lookspan/anthropic	Wrap the Anthropic client
@lookspan/mcp	npm install @lookspan/mcp	Wrap any MCP client
lookspan (PyPI)	pip install lookspan	Generic Python client
lookspan-langgraph	pip install lookspan-langgraph	LangGraph/LangChain callback
lookspan-crewai	pip install lookspan-crewai	CrewAI adapter

See Instrument your agents for usage of each.

Build from source

Lookspan is an npm-workspaces monorepo. To hack on it:

git clone https://github.com/JoniMartin27/lookspan.git
cd lookspan
npm install
npm run dev        # API on :3100, dashboard with hot-reload on :5173
npm run ci         # typecheck + lint + test + build

packages/ holds the internal libraries, apps/ the dashboard, python/ the standalone Python SDKs.