Skip to main content
This guide covers everything you need to install and configure Autonome, from prerequisites to production deployment.

​
System Requirements

​
Hardware

  • CPU: 2+ cores recommended
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 10GB+ for database and logs

​
Software

  • Operating System: Linux, macOS, or WSL2 on Windows
  • Bun: >= 1.1 (required)
  • Node.js: >= 18 (for compatibility)
  • PostgreSQL: >= 15
  • Git: For cloning the repository
Autonome is designed to run on Bun exclusively. Using npm or pnpm is not supported and may cause unexpected behavior.

​
Step 1: Install Prerequisites

1

Install Bun

Bun is required as both the package manager and JavaScript runtime.
curl -fsSL https://bun.sh/install | bash
After installation, add Bun to your PATH:
export PATH="$HOME/.bun/bin:$PATH"
Add this line to your ~/.bashrc, ~/.zshrc, or shell config file to make it permanent.
If you encounter permission errors, ensure your user has write access to ~/.bun/bin.
2

Install PostgreSQL

PostgreSQL is used for persistent storage of trades, positions, and analytics.
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

​
Create Database

Create a dedicated database for Autonome:
# Connect to PostgreSQL
sudo -u postgres psql

# In psql shell:
CREATE DATABASE autonome;
CREATE USER autonome_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE autonome TO autonome_user;
\q
Replace your_secure_password with a strong password. You’ll use this in your DATABASE_URL configuration.
3

Install Node.js (Optional)

While Bun is the primary runtime, Node.js may be needed for some tooling compatibility.
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
Verify installation:
node --version
# Should output: v18.x.x or higher

​
Step 2: Clone and Install Autonome

1

Clone Repository

git clone <your-autonome-repository-url>
cd autonome
2

Install Dependencies

Use Bun to install all project dependencies:
bun install
This will:
  • Install all npm packages defined in package.json
  • Set up TypeScript, Vite, and build tooling
  • Install AI SDK providers and trading integrations
  • Configure Drizzle ORM and database drivers
Do not use npm install or pnpm install. Autonome’s scripts and runtime expect Bun exclusively.
3

Verify Installation

Check that core dependencies are installed:
# Verify Bun can run project scripts
bun run --help

# Check TypeScript compilation
bunx tsc --version

# Verify Drizzle Kit
bunx drizzle-kit --version

​
Step 3: Environment Configuration

Autonome uses T3 Env for type-safe environment configuration. All variables are validated at runtime.
1

Copy Environment Template

cp .env.example .env
2

Configure Core Settings

Open .env and configure these required settings:

​
Database Configuration

.env
# PostgreSQL connection string
DATABASE_URL=postgres://autonome_user:your_secure_password@localhost:5432/autonome
Format: postgres://username:password@host:port/database

​
Server Configuration

.env
# API server port
PORT=8081

# Server URL (for callbacks and webhooks)
SERVER_URL=http://localhost:3000

# Allowed CORS origins (comma-separated, no trailing slash)
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

​
Trading Mode

.env
# Trading mode: "simulated" or "live"
TRADING_MODE=simulated
Start with TRADING_MODE=simulated to test strategies without risk. Switch to live only after thorough testing.
3

Configure AI Providers

Autonome supports multiple AI providers. Configure at least one:
.env
# Get API key from: https://build.nvidia.com/
NIM_API_KEY=nvapi-xxxxxxxxxxxxx

# Optional: Multiple keys for rate limit distribution
NIM_API_KEY1=nvapi-xxxxxxxxxxxxx
NIM_API_KEY2=nvapi-xxxxxxxxxxxxx
NIM_API_KEY3=nvapi-xxxxxxxxxxxxx

​
OpenRouter

.env
# Get API key from: https://openrouter.ai/
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxx
OPENROUTER_API_KEY1=sk-or-xxxxxxxxxxxxx

​
AIHubMix

.env
# Get API key from: https://aihubmix.com/
AIHUBMIX_API_KEY=ahm-xxxxxxxxxxxxx
AIHUBMIX_API_KEY1=ahm-xxxxxxxxxxxxx
AIHUBMIX_API_KEY2=ahm-xxxxxxxxxxxxx

​
Mistral AI

.env
# Get API key from: https://console.mistral.ai/
MISTRAL_API_KEY=xxxxxxxxxxxxx
The platform automatically cycles through available API keys to distribute requests and avoid rate limits. Configure multiple keys per provider for better throughput.
4

Configure Simulator (Optional)

Customize simulator behavior for strategy testing:
.env
# Initial capital for simulated trading
SIM_INITIAL_CAPITAL=10000

# Quote currency (USDT, USDC, etc.)
SIM_QUOTE_CURRENCY=USDT

# Market data refresh interval (milliseconds)
SIM_REFRESH_INTERVAL_MS=10000
5

Configure Lighter API (Live Trading Only)

Required only for live trading mode:
.env
# Lighter API configuration
LIGHTER_API_KEY_INDEX=2
LIGHTER_BASE_URL=https://mainnet.zklighter.elliot.ai
Live trading requires valid Lighter API credentials. Ensure you understand the risks before enabling live mode.
6

Optional: Technical Analysis

For supplementary technical indicators:
.env
# TAAPI.io API key (optional)
# Get key from: https://taapi.io/
TAAPI_API_KEY=xxxxxxxxxxxxx

​
Step 4: Database Setup

1

Generate Migrations

After schema changes (or initial setup), generate migration files:
bun run db:generate
This reads src/db/schema.ts and creates SQL migration files in ./drizzle/.
2

Apply Migrations

Apply migrations to your database:
bun run db:migrate
This executes all pending migrations and sets up your database schema:
  • "Models" - AI model configurations
  • "Orders" - Trade orders and positions
  • "PortfolioSnapshots" - Historical portfolio values
  • Other analytics and tracking tables
3

Seed Initial Data

Populate the database with default AI model variants:
bun run db:seed
This creates four default trading strategies:
VariantStrategyRisk Profile
ApexAggressive momentumHigh risk, high reward
TrendsurferTrend-followingMedium risk
ContrarianCounter-trendMedium-high risk
SovereignBalanced multi-factorModerate risk
You can re-run the seed script anytime to reset your database to default state. This will clear all existing data.
4

Verify Database Setup

Launch Drizzle Studio to inspect your database:
bun run db:studio
This opens a web interface at https://local.drizzle.studio where you can:
  • Browse tables and relationships
  • View seeded data
  • Execute SQL queries
  • Monitor database schema

​
Step 5: Start the Application

1

Development Mode

For local development, start both the API server and frontend:
bun run dev:all
The application will be available at:
2

Production Build

For production deployment:
# Build frontend
bun run build

# Build API server
bun run build:api

# Start production server
bun run start:api
The frontend (src/) deploys to Vercel as a TanStack Start SPA. The API server (api/src/index.ts) runs on a VPS or container platform.

​
Deployment Architecture

Autonome is designed as a split deployment:

​
Frontend (Vercel)

  • Location: src/ directory
  • Framework: TanStack Start (React 19)
  • Build Command: bun run build
  • Output: Static SPA with SSR capabilities
  • Environment: Configure VITE_* prefixed variables

​
Backend (VPS/Container)

  • Location: api/src/index.ts
  • Framework: Hono API server
  • Build Command: bun run build:api
  • Start Command: bun run start:api
  • Port: 8081 (configurable via PORT env var)

​
Communication

  • Frontend calls backend via oRPC over HTTP
  • Development: Vite proxies /api/* to API server
  • Production: Frontend uses VITE_API_URL to reach API

​
Environment Variables Reference

Complete reference of all environment variables:

​
Required Variables

VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgres://user:pass@host:5432/db
TRADING_MODETrading mode (simulated or live)simulated

​
Server Configuration

VariableDescriptionDefault
PORTAPI server port8081
SERVER_URLPublic server URLhttp://localhost:3000
CORS_ORIGINSAllowed frontend origins“
API_URLInternal API URLhttp://localhost:8081

​
Simulator Configuration

VariableDescriptionDefault
SIM_INITIAL_CAPITALStarting capital10000
SIM_QUOTE_CURRENCYQuote currencyUSDT
SIM_REFRESH_INTERVAL_MSPrice refresh interval10000

​
AI Provider Keys

VariableDescription
NIM_API_KEYNVIDIA NIM primary key
NIM_API_KEY1-3Additional NIM keys
OPENROUTER_API_KEYOpenRouter primary key
OPENROUTER_API_KEY1Additional OpenRouter key
AIHUBMIX_API_KEYAIHubMix primary key
AIHUBMIX_API_KEY1-5Additional AIHubMix keys
MISTRAL_API_KEYMistral AI key

​
Lighter API (Live Trading)

VariableDescriptionDefault
LIGHTER_API_KEY_INDEXAPI key slot2
LIGHTER_BASE_URLLighter endpointhttps://mainnet.zklighter.elliot.ai

​
Optional Integrations

VariableDescription
TAAPI_API_KEYTAAPI.io technical analysis
VITE_APP_TITLECustom UI title

​
Client-Side Variables

Variables prefixed with VITE_ are exposed to the browser:
VariableDescription
VITE_API_URLAPI URL for frontend
VITE_APP_TITLEApplication title

​
Verification

After installation, verify everything is working:
1

Check Services

# Verify database connection
bunx drizzle-kit studio

# Test API server
curl http://localhost:8081/health

# Check frontend
open http://localhost:5173
2

Run Tests

# Run test suite
bun run test

# Run linting
bun run lint

# Type check
bunx tsc --noEmit
3

Monitor Logs

Watch application logs for errors:
# API server logs (when running dev:api)
# Frontend logs (when running dev)

​
Common Issues

Symptoms: ECONNREFUSED or Connection refused errorsSolutions:
  1. Verify PostgreSQL is running: 
    sudo systemctl status postgresql
# or
pg_isready
  2. Check PostgreSQL is listening on correct port: 
    sudo netstat -plnt | grep 5432
  3. Verify connection string format: 
    postgres://username:password@localhost:5432/database_name
  4. Test connection manually: 
    psql "postgres://autonome_user:password@localhost:5432/autonome"
Symptoms: bun: command not foundSolutions:
  1. Reinstall Bun: 
    curl -fsSL https://bun.sh/install | bash
  2. Add to PATH: 
    export PATH="$HOME/.bun/bin:$PATH"
  3. Reload shell: 
    source ~/.bashrc
# or
source ~/.zshrc
Symptoms: EADDRINUSE: address already in useSolutions:
  1. Change port in .env: 
    PORT=8082
  2. Kill process using port: 
    # Find process
lsof -ti:8081

# Kill process
kill -9 $(lsof -ti:8081)
  3. Use different port range: 
    PORT=3001
VITE_API_URL=http://localhost:3001
Symptoms: Drizzle migration failuresSolutions:
  1. Ensure database exists: 
    createdb autonome
  2. Check database permissions: 
    GRANT ALL PRIVILEGES ON DATABASE autonome TO autonome_user;
  3. Reset migrations (development only): 
    # Drop all tables
psql autonome -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"

# Re-run migrations
bun run db:migrate
bun run db:seed
Symptoms: Invalid environment variables or validation errorsSolutions:
  1. Check .env file exists: 
    ls -la .env
  2. Validate required variables are set: 
    cat .env | grep DATABASE_URL
cat .env | grep TRADING_MODE
  3. Ensure no trailing spaces or quotes: 
    # Correct
DATABASE_URL=postgres://...

# Incorrect
DATABASE_URL="postgres://..."
DATABASE_URL=postgres://...
  4. Restart server after changing .env

​
Next Steps

Quickstart Guide

Get your first trading bot running in minutes

Configuration

Customize AI models, risk parameters, and strategies

Architecture

Understand the system design and data flow

API Reference

Explore oRPC procedures and integrations

​
Additional Resources

  • Database Schema: See src/db/schema.ts for complete data model
  • Environment Validation: Check src/env.ts for all validated variables
  • Commands Reference: Run bun run to list all available scripts
  • Drizzle Kit: Use bunx drizzle-kit --help for database utilities

Build docs developers (and LLMs) love

Get started for freeTalk to us