Dune

Dune is a local-first agent workspace for coordinating agents, channels, sandboxes, and mini-apps from one UI.

What Dune Does

• Organizes work in channels so humans and agents can coordinate around shared threads.
• Lets you create agents, start or stop them, inspect logs, manage todos, review skills, and open their computer view.
• Provides sandbox operations for lifecycle control, command execution, file browsing, uploads, downloads, and host-path import.
• Surfaces mini-apps built by agents in the same workspace.
• Keeps runtime state local with SQLite storage and BoxLite-backed sandboxes and agent runtimes.

Quick Start

Prerequisites:

• Node.js 24
• corepack available for pnpm 9
• make

git clone <repo-url>
cd dune
corepack enable
make deploy
make run

Open http://localhost:3100.

make deploy installs dependencies, creates .env from .env.example if needed, and builds all packages. Before agents can actually respond, configure a model provider in Settings > Model.

Common Commands

Command	What it does
make deploy	Install dependencies, create .env if missing, and build the app.
make build	Build shared, backend, frontend, and Electron packages.
make test	Run the backend test suite.
make check	Run the pre-PR validation gate: build plus backend tests.
make run	Start the app with the built frontend assets.
make dev	Start backend, frontend, and Electron together for local development.
make electron-dev	Launch Electron only when backend and frontend dev servers are already running.
make electron-pack	Build an unpacked Electron package for local testing.
make package	Build an installable Electron app for the current platform.
pnpm --filter @dune/frontend e2e:electron	Run the opt-in Electron smoke E2E against the built app.
make clean	Remove build and dev artifacts while keeping local runtime data.

Development Mode

For the default local development loop:

make deploy
make dev

make dev uses scripts/dev.mjs to start the backend, Vite frontend, and Electron together.

Use the split backend/frontend workflow below when you want live frontend iteration without Electron or you need to follow the sandbox manual checklist.

1. Build dependencies once:

make deploy

2. Start the backend from the repo root:

PORT=3100 DATA_DIR=./test-results/manual-checks/data pnpm --filter @dune/backend dev

3. Start the frontend dev server in another terminal:

pnpm --filter @dune/frontend dev -- --host localhost --port 4173

4. Open http://localhost:4173.

5. If you want Electron on top of those existing dev servers, run in a third terminal:

make electron-dev

Monorepo Layout

• packages/frontend: Lit-based SPA, workspace shell, agent views, sandbox UI, and apps UI.
• packages/backend: Hono server, WebSocket layer, SQLite stores, agent orchestration, and sandbox APIs.
• packages/shared: shared schemas and types used by both frontend and backend.

Data and Configuration

• DATA_DIR defaults to ./data and relocates the full runtime data root.
• The SQLite database lives at data/db/dune.db.
• Agent files live under data/agents/.
• BoxLite state lives at data/boxlite/.
• PORT defaults to 3100.
• ADMIN_PORT defaults to PORT + 1 and binds the admin plane to 127.0.0.1.
• FRONTEND_DIST_PATH defaults to ./packages/frontend/dist; make run serves the built SPA from there.
• Local tool state in .claude/ and .codex/, runtime data in data/, and generated artifacts such as dist/, test-results/, coverage/, .release/, and packages/backend/.port are intentionally local-only and git-ignored.
• If you want an isolated run for manual checks or demos, point DATA_DIR at another ignored path such as ./test-results/manual-checks/data.

Further Reading

• Sandboxes UI Manual Verification Checklist
• Deployment Function UI Design