ImpoDocs
Browse documentation

DocumentationStart here

Run it locally

Start the API and worker, send a durable command, then choose a client.

On this pageGet the sourceStart the database and servicesSend your first commandChoose a clientEnable real agent executionVerify your environment

The smallest full backend uses Node.js 22 or newer and local PostgreSQL binaries. It uses development identities and a deterministic runtime. You do not need a model key to verify command acceptance and recovery.

Get the source#

Terminal
git clone https://github.com/impoai/impo.git
cd impo
npm ci
cp .env.example .env

Keep .env local. The example binds the API to 127.0.0.1:3001, uses a local database and selects INSTANT_RUNTIME=development.

Start the database and services#

From the repository root:

Terminal
npm run db:start
npm run db:push
npm run db:seed
npm run dev:api

In a second terminal, also at the repository root:

Terminal
npm run dev:worker

The API admits work; the worker executes it. Running only the API can leave accepted work waiting. /health reports process health, and /ready checks database/schema readiness.

Send your first command#

Use the seeded Alice development identity. The same clientMessageId must be reused if you retry this exact command after an uncertain response.

Terminal
IMPO_DEV_TOKEN=instant-dev-alice
curl http://127.0.0.1:3001/api/v1/conversation/messages \
  -H "Authorization: Bearer $IMPO_DEV_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"clientMessageId":"8afca1e1-2a98-4367-a0d0-7315e8bad101","text":"Hello, Impo"}'

The response contains a submission receipt. Read /api/v1/submissions/<submissionId> for status or subscribe at /api/v1/submissions/<submissionId>/stream. Read /api/v1/conversation to recover history. The development runtime verifies the protocol; it is not a real agent response.

Choose a client#

ClientStart here
Webnpm run dev:web; use the Web guide to configure the API and Clerk environment.
iOSnpm run generate:ios, then open ios/App/Instant.xcodeproj in Xcode. Follow the iOS guide for signing and development settings.
Androidnpm run build:android; follow the Android guide for the SDK, emulator and backend settings.
MacFollow the Desktop guide for the Electron build, native helper and local API settings.

For Web UI work without an account, use the separate in-memory fixture:

Terminal
# Terminal 1
npm run dev:web:fixture

# Terminal 2
IMPO_WEB_API_ORIGIN=http://127.0.0.1:3041 VITE_IMPO_FIXTURE=1 npm run dev:web

The fixture has synthetic accounts and resets when stopped. Its tokens and port differ from the PostgreSQL-backed development API above. Do not mix their data or authentication.

Enable real agent execution#

Set INSTANT_RUNTIME=rebyte and REBYTE_API_KEY in the local .env, then restart both services. The server uses the official openai client's client.beta.agents with @rebyteai/agent-extensions. Keep the key on the server.

Connectors, speech, Temporal scheduling and remote storage each need their own configuration. Add them when your feature needs them; see deployment and services.

Verify your environment#

Terminal
npm run typecheck
npm run test:server
npm run test:db

test:db needs PostgreSQL and creates isolated test clusters. npm test also exercises Swift and the client protocol, so it requires the Swift toolchain. A passing fixture test does not prove physical microphone, Bluetooth or background behavior.