Development Setup

Prerequisites

You need three things installed before starting:

Optional tools (only needed if you’re working on specific engines):

• Playwright - for engine-web development
• Appium - for engine-mobile development

Clone and install

git clone https://github.com/autonoma-ai/autonoma.git
cd agent
pnpm install

pnpm install handles the entire monorepo - all apps and packages get their dependencies in one pass.

Start infrastructure

PostgreSQL and Redis run via Docker Compose:

docker compose up -d

This starts:

• PostgreSQL 18 on localhost:5432 (user: postgres, password: postgres)
• Redis on localhost:6379

Verify they’re running:

docker compose ps

Both containers should show running status.

Environment variables

Copy the example file and fill in the required values:

cp .env.example .env

Minimum required variables

How environment variables work in the codebase

The project uses createEnv from @t3-oss/env-core for environment variable validation. Each app has an env.ts file that defines its required variables with Zod schemas. Variables are validated at startup - if something is missing, you get a clear error message telling you exactly what to add.

You should never read process.env directly in application code. Instead, import from the app’s env.ts file.

See .env.example for the full list of variables grouped by service. Most optional variables have sensible defaults or are only needed for specific features (S3 storage, Sentry, PostHog, etc.).

Database setup

Generate the Prisma client and run migrations:

pnpm db:generate
pnpm db:migrate

db:generate creates the TypeScript client from the Prisma schema. db:migrate applies all migrations to create the database tables.

You need to re-run db:generate whenever the Prisma schema changes (after pulling new changes or editing the schema yourself).

Start development servers

pnpm dev

This starts both servers concurrently:

• UI at http://localhost:3000 (Vite + React)
• API at http://localhost:4000 (Hono + tRPC)

To run them individually:

pnpm api    # API only (port 4000)
pnpm ui     # UI only (port 3000)

Verify everything works

1. Open http://localhost:3000 in your browser
2. You should see the login page
3. Sign in with Google OAuth
4. If you see the dashboard, everything is working

Run the full check suite to make sure nothing is broken:

pnpm typecheck    # TypeScript type checking
pnpm lint         # ESLint
pnpm test         # Vitest
pnpm build        # Full build

Other useful commands

Troubleshooting

pnpm install fails

Make sure you’re using pnpm 10.x. Run corepack enable to let Node manage the pnpm version, then try again.

Database connection refused

Check that Docker Compose is running: docker compose ps. If PostgreSQL isn’t up, check logs with docker compose logs postgres.

Prisma generate fails

This usually means dependencies aren’t installed. Run pnpm install first, then pnpm db:generate.

Port already in use

Another process is using port 3000 or 4000. Find and kill it:

lsof -i :3000  # or :4000
kill <PID>

Google OAuth redirect error

Make sure your Google Cloud OAuth credentials have http://localhost:4000/api/auth/callback/google as an authorized redirect URI.

”Missing environment variable” error on startup

The app validates all required environment variables at startup using createEnv. Check the error message for which variable is missing, then add it to your .env file.

TypeScript errors after pulling changes

Run pnpm db:generate first (the Prisma client may have changed), then pnpm build to rebuild all packages. TypeScript errors in the UI or API often come from stale package builds.