ImpoDocs
Browse documentation

DocumentationStart here

Run it locally

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

2 min readDeveloper guide
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 personal-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.

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 @rebyteai/agent-sdk and client.beta.agents. 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.

Read page source ↗Discuss on Discord ↗