Local Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Bun >= 1.1 (package manager and runtime)
Node.js 18+ (for compatibility)
PostgreSQL 15+ (local or hosted)
Git (for version control)

Autonome uses Bun exclusively as its package manager. Never use npm or pnpm.

Installation Steps

1. Clone the Repository

git clone <repository-url>
cd autonome

2. Install Dependencies

Use Bun to install all project dependencies:

bun install

This will install all packages defined in package.json, including:

TanStack Start framework
React 19 and related libraries
Database tools (Drizzle ORM)
AI SDK and provider integrations
UI components (shadcn/ui, Tailwind CSS v4)

3. Configure Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and fill in the required values:

Required Variables

# Database
DATABASE_URL=postgres://user:password@localhost:5432/autonome

# Server Configuration
PORT=8081                    # Backend API server port
FRONTEND_PORT=5173          # Frontend dev server port
VITE_API_URL=http://localhost:8081  # API URL for browser
SERVER_URL=http://localhost:3000

# Trading Mode
TRADING_MODE=simulated      # Use 'simulated' for local dev, 'live' for production

# Lighter API (for live trading)
LIGHTER_API_KEY_INDEX=2
LIGHTER_BASE_URL=https://mainnet.zklighter.elliot.ai

Optional Variables

# AI Provider Keys (optional for development)
MISTRAL_API_KEY=your_key_here
NIM_API_KEY=your_key_here
OPENROUTER_API_KEY=your_key_here

# CORS (for production deployments)
CORS_ORIGINS=https://autonome.app,https://autonome.vercel.app

# Sentry (for error tracking)
VITE_SENTRY_DSN=your_dsn_here

Environment Variable Naming:

PORT and FRONTEND_PORT are server-side only (accessed via process.env)
Variables prefixed with VITE_ are exposed to the browser (accessed via import.meta.env)
Always use src/env.ts (T3Env) instead of accessing process.env directly

4. Set Up PostgreSQL Database

Local PostgreSQL Setup

If you don’t have PostgreSQL installed: macOS (Homebrew):

brew install postgresql@15
brew services start postgresql@15

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install postgresql-15
sudo systemctl start postgresql

Create Database:

psql postgres
CREATE DATABASE autonome;
CREATE USER autonome_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE autonome TO autonome_user;
\q

Update your DATABASE_URL in .env:

DATABASE_URL=postgres://autonome_user:your_password@localhost:5432/autonome

Using Hosted PostgreSQL

Alternatively, use a hosted PostgreSQL service:

Supabase: Free tier with generous limits
Neon: Serverless PostgreSQL with branching
Railway: Simple deployment and database hosting

5. Run Database Migrations

Apply the database schema:

bun run db:migrate

This creates all necessary tables with Drizzle’s quoted identifiers (e.g., "Models", "Orders", "Trades").

Use bun run db:studio to launch Drizzle Studio and visually inspect your database schema.

6. Seed the Database (Optional)

Populate the database with default AI models:

bun run db:seed

This creates entries in the "Models" table for the four trading variants:

Apex: Aggressive high-frequency trading
Trendsurfer: Momentum-based trading
Contrarian: Counter-trend strategies
Sovereign: Conservative long-term positions

Running the Development Servers

Autonome has a split architecture with separate frontend and backend servers:

Development Commands

Run Both Servers Concurrently

bun run dev:all

This starts:

API server on port 8081 (Hono backend)
Frontend server on port 5173 (Vite + TanStack Start)

Use this command for full-stack development.

Run API Server Only

bun run dev:api

Starts the Hono API server with hot reload on port 8081. Use when:

Working on backend logic, oRPC procedures, or database queries
Testing API endpoints independently
Running the scheduler bootstrap

Run Frontend Only

bun run dev

Starts the Vite dev server with TanStack Start on port 5173. Use when:

Working on UI components and styles
The API server is already running separately
Testing frontend-only changes

Vite Proxy Configuration: The frontend dev server automatically proxies /api/* requests to the backend API server at http://localhost:8081. This is configured in vite.config.ts.

When to Use Each Command

Command	Use Case
`bun run dev:all`	Default choice - Full-stack development with both servers
`bun run dev:api`	Backend-focused work, oRPC procedures, database operations
`bun run dev`	Frontend-focused work, UI components, styling

Verifying Your Setup

1. Check Environment Configuration

Run the environment validation script:

bun run scripts/validate-env.ts

This verifies all required environment variables are set correctly.

2. Access the Application

Once the dev servers are running:

Frontend: http://localhost:5173
API: http://localhost:8081
API Health Check: http://localhost:8081/health (if implemented)

3. Test Database Connection

Open Drizzle Studio to verify database connectivity:

bun run db:studio

This opens a web interface at http://localhost:4983 to browse your database.

Troubleshooting

Port Already in Use

Error: EADDRINUSE: address already in use Solution: Check if another process is using the port:

# Check what's using port 8081 or 5173
lsof -i :8081
lsof -i :5173

# Kill the process
kill -9 <PID>

Or change the ports in your .env file:

PORT=8082
FRONTEND_PORT=5174
VITE_API_URL=http://localhost:8082

Database Connection Failed

Error: Connection refused or authentication failed Solutions:

Verify PostgreSQL is running:

# macOS
brew services list | grep postgresql

# Linux
sudo systemctl status postgresql

Check DATABASE_URL format:

# Correct format
postgres://username:password@host:port/database

Test connection manually:
psql "$DATABASE_URL"

Bun Installation Issues

Error: bun: command not found Solution: Install Bun:

curl -fsSL https://bun.sh/install | bash

# Add to PATH (if not automatic)
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Module Resolution Errors

Error: Cannot find module '@/...' Solution: Ensure TypeScript path aliases are configured. Check tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Then restart the dev server.

Migration Errors

Error: relation "Models" does not exist Solutions:

Generate migrations after schema changes:
bun run db:generate
Apply migrations:
bun run db:migrate

Reset database (destructive):

# Drop all tables and recreate
psql "$DATABASE_URL" -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
bun run db:migrate
bun run db:seed

Vite Build Errors

Error: Build fails with TypeScript errors Solution: Run type checking:

bun run check

Fix any reported type errors before running the dev server.

API Proxy Not Working

Symptom: Frontend can’t reach API endpoints Solutions:

Verify API server is running:
curl http://localhost:8081/health
Check VITE_API_URL in .env:
VITE_API_URL=http://localhost:8081
Restart frontend dev server after changing environment variables.

Next Steps

Now that your development environment is set up:

Explore the codebase: Review Architecture to understand the project structure
Run tests: See Testing for testing strategies
Follow code style: Read Code Style for Biome rules and conventions
Start coding: Check out the Contributing Guide for development workflow

Use bun run dev:all with TRADING_MODE=simulated to test trading strategies without connecting to real exchanges.

​Prerequisites

​Installation Steps

​1. Clone the Repository

​2. Install Dependencies

​3. Configure Environment Variables

​Required Variables

​Optional Variables

​4. Set Up PostgreSQL Database

​Local PostgreSQL Setup

​Using Hosted PostgreSQL

​5. Run Database Migrations

​6. Seed the Database (Optional)

​Running the Development Servers

​Development Commands

​Run Both Servers Concurrently

​Run API Server Only

​Run Frontend Only

​When to Use Each Command

​Verifying Your Setup

​1. Check Environment Configuration

​2. Access the Application

​3. Test Database Connection

​Troubleshooting

​Port Already in Use

​Database Connection Failed

​Bun Installation Issues

​Module Resolution Errors

​Migration Errors

​Vite Build Errors

​API Proxy Not Working

​Next Steps

Prerequisites

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

Required Variables

Optional Variables

4. Set Up PostgreSQL Database

Local PostgreSQL Setup

Using Hosted PostgreSQL

5. Run Database Migrations

6. Seed the Database (Optional)

Running the Development Servers

Development Commands

Run Both Servers Concurrently

Run API Server Only

Run Frontend Only

When to Use Each Command

Verifying Your Setup

1. Check Environment Configuration

2. Access the Application

3. Test Database Connection

Troubleshooting

Port Already in Use

Database Connection Failed

Bun Installation Issues

Module Resolution Errors

Migration Errors

Vite Build Errors

API Proxy Not Working

Next Steps