@alook/app

Run Alook locally — one command, no clone needed.

Quick Start

npx @alook/app onboard

This will:

1. Check your environment (Node.js >= 20, AI runtime)
2. Install Alook to ~/.alook/self-hosted/
3. Generate secrets (BETTER_AUTH_SECRET, ENCRYPTION_KEY)
4. Run database migrations (SQLite via Cloudflare D1 local)
5. Start all services (web, email worker, WebSocket, wake worker)
6. Create your local account
7. Pair this machine and start @alook/daemon
8. Open the dashboard in your browser

Commands

Embedded daemon

@alook/app bundles the current @alook/daemon CLI. Pairing happens automatically during onboard; saved machine credentials remain private in the app-owned data directory.

npx @alook/app daemon list                   # List paired/running daemons
npx @alook/app daemon status [machine-id]    # Check agent status
npx @alook/app daemon stop <machine-id>      # Stop one daemon
npx @alook/app daemon start --id <machine-id> # Restart without exposing its credential

Options

--port-web <port>    Web server port (default: 15210)
--port-email <port>  Email worker port (default: 15211)
--port-ws <port>     WebSocket worker port (default: 15212)
--port-wake <port>   Wake worker port (default: 15213)
--skip-register      Skip account creation (onboard only)

Architecture

Services

Alook runs four local services, each in its own Wrangler dev process:

All services share a single SQLite database (Cloudflare D1 local mode) with state persisted at ~/.alook/self-hosted/web/.wrangler/state/.

Directory Layout

~/.alook/self-hosted/
├── web/                  # Web app (wrangler.toml, migrations, .dev.vars)
│   ├── .wrangler/state/  # D1 database & KV persistence
│   └── migrations/       # SQL migration files
├── email-worker/         # Email worker (wrangler.toml, .dev.vars)
├── ws-do/                # WebSocket Durable Object worker
├── queue-worker/         # Queue task consumer (agent wake + mobile push)
├── daemon/               # Private machine credentials, daemon state, and logs
├── logs/                 # Service logs (web, email, WS, and wake workers)
└── .pids.json            # PID tracking for running services

Database Migrations

Migrations are SQL files applied via wrangler d1 migrations apply --local. They run automatically during:

• onboard — applies all migrations on fresh install
• update — applies any new migrations after installing the latest version

Wrangler tracks which migrations have been applied; only pending ones are executed.

Secrets Management

On first onboard, secrets are auto-generated and written to .dev.vars files:

• Web: BETTER_AUTH_SECRET, BETTER_AUTH_URL, ENCRYPTION_KEY, OAuth client ID/secret placeholders
• Email Worker: ENCRYPTION_KEY (synced from web)

Secrets are never overwritten on subsequent runs — only missing files are created.

Dev Mode

When the ALOOK_PROJECT_ROOT environment variable is set, @alook/app runs in dev mode against the monorepo:

• Runs pnpm predev to set up environment files
• Runs pnpm db:migrate for migrations (instead of Wrangler CLI)
• Starts web via next dev (instead of Wrangler)
• Services run in foreground with prefixed log output ([web], [email-worker], [ws-do])
• Ctrl+C cleanly stops all services

ALOOK_PROJECT_ROOT=/path/to/alook npx @alook/app onboard

Requirements

• Node.js >= 20.9
• A supported agent runtime such as Claude Code, Codex, OpenCode, Pi, or Cursor

Limitations

• Email send/receive is not available in local mode
• OAuth login (GitHub, Google) is disabled; use email/password

License

Apache-2.0 — see LICENSE.