Skip to main content

​
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

CommandUse Case
bun run dev:allDefault choice - Full-stack development with both servers
bun run dev:apiBackend-focused work, oRPC procedures, database operations
bun run devFrontend-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:

​
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:
  1. Verify PostgreSQL is running: 
    # macOS
brew services list | grep postgresql

# Linux
sudo systemctl status postgresql
  2. Check DATABASE_URL format: 
    # Correct format
postgres://username:password@host:port/database
  3. 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:
  1. Generate migrations after schema changes: 
    bun run db:generate
  2. Apply migrations: 
    bun run db:migrate
  3. 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:
  1. Verify API server is running: 
    curl http://localhost:8081/health
  2. Check VITE_API_URL in .env: 
    VITE_API_URL=http://localhost:8081
  3. Restart frontend dev server after changing environment variables.

​
Next Steps

Now that your development environment is set up:
  1. Explore the codebase: Review Architecture to understand the project structure
  2. Run tests: See Testing for testing strategies
  3. Follow code style: Read Code Style for Biome rules and conventions
  4. 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us