---
title: Run it locally
description: Start the API and worker, send a durable command, then choose a client.
---

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

```sh
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:

```sh
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:

```sh
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.

```sh
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

| Client | Start here |
| --- | --- |
| Web | `npm run dev:web`; use the [Web guide](https://github.com/impoai/impo/blob/main/web/README.md) to configure the API and Clerk environment. |
| iOS | `npm run generate:ios`, then open `ios/App/Instant.xcodeproj` in Xcode. Follow the [iOS guide](https://github.com/impoai/impo/blob/main/ios/App/README.md) for signing and development settings. |
| Android | `npm run build:android`; follow the [Android guide](https://github.com/impoai/impo/blob/main/android/README.md) for the SDK, emulator and backend settings. |

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

```sh
# 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](/docs/extend/deployment/).

## Verify your environment

```sh
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.