Quickstart

Install the two apps and bring up the backend and frontend dev servers.

UseAgent runs as two standalone apps that share a Postgres database. This page gets both dev servers up locally.

Prerequisites

Bun as the runtime and package manager. UseAgent uses Bun everywhere, never npm.
Postgres with the pgvector extension available. The backend is the source of truth and applies its Drizzle migrations on boot; one migration runs CREATE EXTENSION IF NOT EXISTS vector, so the server must have pgvector installed and the connecting role must be able to create the extension (or it must already exist in the database).

Install

The two apps and the five shared packages each carry their own lockfile, so install inside each one:

(cd frontend && bun install)
(cd backend && bun install)
for p in packages/*/; do (cd "$p" && bun install); done

The package installs matter on a fresh clone: the root bun run typecheck runs tsc inside every packages/* directory, which needs each package’s own devDependencies.

Environment

Local dev is designed to boot with almost no configuration:

DATABASE_URL defaults to postgres://postgres@localhost:5432/useagent.
BETTER_AUTH_SECRET falls back to an insecure dev default while dev mode is on; the backend warns at boot. Production requires a real secret.
Requests without a session fall back to a seeded dev org and user, so every API works unauthenticated in local dev.

Live model and sandbox work needs real keys in backend/.env:

A live chat turn needs OPENROUTER_API_KEY.
A sandboxed agent run needs a sandbox provider key: DAYTONA_API_KEY with the default SANDBOX_PROVIDER=daytona.

Run the dev servers

From the repository root:

bun run dev:backend    # Hono control plane on :3201
bun run dev:frontend   # Next.js UI on :3400

The frontend proxies browser /api/* requests to the backend, so you interact with the product entirely through http://localhost:3400.

Backend is listening

:3201 answers and the boot migrator has applied the schema. Needs only Postgres with pgvector.

Frontend is up

http://localhost:3400 loads the chat surface. A live chat turn needs OPENROUTER_API_KEY.

A run streams

Start an agent run and watch steps arrive live in the session timeline. Needs a sandbox provider key (DAYTONA_API_KEY by default).

Root scripts

The root scripts you will actually use day to day are:

bun run dev:backend      # Hono control plane on :3201
bun run dev:frontend     # Next.js UI on :3400
bun run typecheck        # frontend, backend, and all five shared packages

bun run typecheck must pass before any change is considered done. The remaining root scripts (release:hosted, canary:hosted-release, release:provider-connection-bootstrap, stage:t3-dist) are deploy-lane tooling covered in Operations. For the full test and operations toolset, see Verification.