Installation

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

Install Bun

Bun is required as both the package manager and JavaScript runtime.

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

# Install WSL2 first, then:
curl -fsSL https://bun.sh/install | bash

bun --version
# Should output: bun 1.1.0 or higher

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.

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

brew install postgresql@15
brew services start postgresql@15

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo service postgresql start

docker run --name autonome-postgres \
  -e POSTGRES_PASSWORD=yourpassword \
  -e POSTGRES_DB=autonome \
  -p 5432:5432 \
  -d postgres:15

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.

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

brew install node@18

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Verify installation:

node --version
# Should output: v18.x.x or higher

Step 2: Clone and Install Autonome

Clone Repository

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

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.

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.

Copy Environment Template

cp .env.example .env

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.

Configure AI Providers

Autonome supports multiple AI providers. Configure at least one:

NVIDIA NIM (Recommended)

.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.

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

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.

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

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/.

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

Seed Initial Data

Populate the database with default AI model variants:

bun run db:seed

This creates four default trading strategies:

Variant	Strategy	Risk Profile
Apex	Aggressive momentum	High risk, high reward
Trendsurfer	Trend-following	Medium risk
Contrarian	Counter-trend	Medium-high risk
Sovereign	Balanced multi-factor	Moderate risk

You can re-run the seed script anytime to reset your database to default state. This will clear all existing data.

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

Development Mode

For local development, start both the API server and frontend:

bun run dev:all

bun run dev:api

bun run dev

The application will be available at:

Frontend: http://localhost:5173
API Server: http://localhost:8081

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

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgres://user:pass@host:5432/db`
`TRADING_MODE`	Trading mode (`simulated` or `live`)	`simulated`

Server Configuration

Variable	Description	Default
`PORT`	API server port	`8081`
`SERVER_URL`	Public server URL	`http://localhost:3000`
`CORS_ORIGINS`	Allowed frontend origins	“
`API_URL`	Internal API URL	`http://localhost:8081`

Simulator Configuration

Variable	Description	Default
`SIM_INITIAL_CAPITAL`	Starting capital	`10000`
`SIM_QUOTE_CURRENCY`	Quote currency	`USDT`
`SIM_REFRESH_INTERVAL_MS`	Price refresh interval	`10000`

AI Provider Keys

Variable	Description
`NIM_API_KEY`	NVIDIA NIM primary key
`NIM_API_KEY1-3`	Additional NIM keys
`OPENROUTER_API_KEY`	OpenRouter primary key
`OPENROUTER_API_KEY1`	Additional OpenRouter key
`AIHUBMIX_API_KEY`	AIHubMix primary key
`AIHUBMIX_API_KEY1-5`	Additional AIHubMix keys
`MISTRAL_API_KEY`	Mistral AI key

Lighter API (Live Trading)

Variable	Description	Default
`LIGHTER_API_KEY_INDEX`	API key slot	`2`
`LIGHTER_BASE_URL`	Lighter endpoint	`https://mainnet.zklighter.elliot.ai`

Optional Integrations

Variable	Description
`TAAPI_API_KEY`	TAAPI.io technical analysis
`VITE_APP_TITLE`	Custom UI title

Client-Side Variables

Variables prefixed with VITE_ are exposed to the browser:

Variable	Description
`VITE_API_URL`	API URL for frontend
`VITE_APP_TITLE`	Application title

Verification

After installation, verify everything is working:

Check Services

# Verify database connection
bunx drizzle-kit studio

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

# Check frontend
open http://localhost:5173

Run Tests

# Run test suite
bun run test

# Run linting
bun run lint

# Type check
bunx tsc --noEmit

Monitor Logs

Watch application logs for errors:

# API server logs (when running dev:api)
# Frontend logs (when running dev)

Common Issues

DATABASE_URL connection refused

Symptoms: ECONNREFUSED or Connection refused errorsSolutions:

Verify PostgreSQL is running:

sudo systemctl status postgresql
# or
pg_isready

Check PostgreSQL is listening on correct port:
sudo netstat -plnt | grep 5432

Verify connection string format:

postgres://username:password@localhost:5432/database_name

Test connection manually:

psql "postgres://autonome_user:password@localhost:5432/autonome"

Bun command not found

Symptoms: bun: command not foundSolutions:

Reinstall Bun:

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

Add to PATH:
export PATH="$HOME/.bun/bin:$PATH"
Reload shell:
source ~/.bashrc # or source ~/.zshrc

Port already in use

Symptoms: EADDRINUSE: address already in useSolutions:

Change port in .env:
PORT=8082

Kill process using port:

# Find process
lsof -ti:8081

# Kill process
kill -9 $(lsof -ti:8081)

Use different port range:

PORT=3001
VITE_API_URL=http://localhost:3001

Migration errors

Symptoms: Drizzle migration failuresSolutions:

Ensure database exists:
createdb autonome

Check database permissions:

GRANT ALL PRIVILEGES ON DATABASE autonome TO autonome_user;

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

Environment variable errors

Symptoms: Invalid environment variables or validation errorsSolutions:

Check .env file exists:
ls -la .env

Validate required variables are set:

cat .env | grep DATABASE_URL
cat .env | grep TRADING_MODE

Ensure no trailing spaces or quotes:

# Correct
DATABASE_URL=postgres://...

# Incorrect
DATABASE_URL="postgres://..."
DATABASE_URL=postgres://... 

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

Get Started

Core Features

Deployment

System Requirements

Hardware

Software

Step 1: Install Prerequisites

Create Database

Step 2: Clone and Install Autonome

Step 3: Environment Configuration

Database Configuration

Server Configuration

Trading Mode

NVIDIA NIM (Recommended)

OpenRouter

AIHubMix

Mistral AI

Step 4: Database Setup

Step 5: Start the Application

Deployment Architecture

Frontend (Vercel)

Backend (VPS/Container)

Communication

Environment Variables Reference

Required Variables

Server Configuration

Simulator Configuration

AI Provider Keys

Lighter API (Live Trading)

Optional Integrations

Client-Side Variables

Verification

Common Issues

Next Steps

Quickstart Guide

Configuration

Architecture

API Reference

Additional Resources

​System Requirements

​Hardware

​Software

​Step 1: Install Prerequisites

​Create Database

​Step 2: Clone and Install Autonome

​Step 3: Environment Configuration

​Database Configuration

​Server Configuration

​Trading Mode

​NVIDIA NIM (Recommended)

​OpenRouter

​AIHubMix

​Mistral AI

​Step 4: Database Setup

​Step 5: Start the Application

​Deployment Architecture

​Frontend (Vercel)

​Backend (VPS/Container)

​Communication

​Environment Variables Reference

​Required Variables

​Server Configuration

​Simulator Configuration

​AI Provider Keys

​Lighter API (Live Trading)

​Optional Integrations

​Client-Side Variables

​Verification

​Common Issues

​Next Steps

Quickstart Guide

Configuration

Architecture

API Reference

​Additional Resources

System Requirements

Hardware

Software

Step 1: Install Prerequisites

Create Database

Step 2: Clone and Install Autonome

Step 3: Environment Configuration

Database Configuration

Server Configuration

Trading Mode

NVIDIA NIM (Recommended)

OpenRouter

AIHubMix

Mistral AI

Step 4: Database Setup

Step 5: Start the Application

Deployment Architecture

Frontend (Vercel)

Backend (VPS/Container)

Communication

Environment Variables Reference

Required Variables

Server Configuration

Simulator Configuration

AI Provider Keys

Lighter API (Live Trading)

Optional Integrations

Client-Side Variables

Verification

Common Issues

Next Steps

Additional Resources