Local setup
Everything runs from source with hot reload. Docker runs the infrastructure; your machine runs the apps.
Prerequisites
Section titled “Prerequisites”| Tool | Version | Why |
|---|---|---|
| Node.js | 26.13.0 (.nvmrc; fnm or nvm) |
Everything |
| pnpm | 10.15.0 | The only package manager here |
| Docker | Recent | Postgres, Redis, Temporal, RustFS, Mailpit |
Rust (~/.cargo/bin) |
Stable | Desktop app only |
| Expo Go on a phone | Matching Expo SDK 54 | Phone app only |
First run
Section titled “First run”pnpm install # also runs plugin codegenpnpm dev:setup # .env files, Docker services, migrations, seedpnpm demo:seed # demo people and each plugin's demo datapnpm dev # API + workers (:3000), user app (:5173), App Admin (:5174)pnpm dev runs the instance described by instances/local.yaml. Plugins not listed there are
not built or migrated.
Other apps
Section titled “Other apps”pnpm desktop:dev # desktop app (needs Rust); loads the user app from :5173pnpm mobile:go # Metro for Expo Go; scan the QR code with the phonepnpm docs:dev # reference docs (:3005)pnpm handbook:dev # this handbook (:3006)pnpm manager:dev # App Manager (:3100 API, :5175 app); only when working on itFor the phone, set EXPO_PUBLIC_API_URL in apps/mobile/.env to your machine’s Wi-Fi address
(http://<ip>:3000); the phone cannot reach localhost.
| Port | What |
|---|---|
| 3000 | API (/api/v1, /events, /health) |
| 5173 | User app (also the desktop app’s screens) |
| 5174 | App Admin |
| 8081 | Metro (phone) |
| 3005 / 3006 | Reference docs / this handbook |
| 3100 / 5175 | App Manager API / app |
| 5432 | Postgres (dev:setup picks the next free port if taken) |
| 6379 | Redis |
| 7233 / 8233 | Temporal / its UI |
| 9000 / 9001 | RustFS (S3) / its console |
| 1025 / 8025 | Mailpit SMTP / inbox — every email sent locally lands here |
Every instance on one machine shares these Docker services (compose project antfabric-core).
When they are already running, dev:setup writes the ports they are published on into the new
instance’s .env. Give each instance its own TEMPORAL_NAMESPACE, or its workers pick up
workflows another instance scheduled.
Accounts
Section titled “Accounts”| Account | Password | Role |
|---|---|---|
admin@example.com |
Admin@123456 |
admin: App Admin, and managers’ rights in plugins. First sign-in asks for an authenticator app |
ada, grace, alan, katherine, linus @demo.test |
Demo-Pass-1! |
user |
Browser tabs of the same site share one session. To act as several people at once, use separate browser profiles or a private window, plus the desktop app and the phone.
When something is stuck
Section titled “When something is stuck”| Symptom | Cause and fix |
|---|---|
| The app shows “Restoring your session” forever | The API is not answering. Check curl localhost:3000/health/live and the API lines of pnpm dev; restart it |
| A new plugin screen does not show on the phone | Metro missed a changed file. pnpm --filter mobile start:clear |
| A new plugin is missing everywhere | It is not in instances/local.yaml, or pnpm install did not run codegen |
| “Cannot reach the server” on the desktop app | The API is down, or CORS is missing a header for the desktop client |