Skip to main content

​
Local Development

Run each service individually for development with hot-reload.

​
Prerequisites

  • Python 3.10+
  • Node.js 20+
  • PostgreSQL running locally
  • Better Auth credentials and Postgres password in the root .env. All other provider keys are configured via the dashboard.

​
Database Setup

Create the database in PostgreSQL: 
CREATE DATABASE arkenos;

​
Backend

cd backend

# Create virtual environment
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Run database migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --reload
Backend runs at http://localhost:8000.

​
Frontend

cd frontend

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your credentials

# Start dev server
npm run dev
Frontend runs at http://localhost:3000.

​
Agent

cd agent

# Create virtual environment
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -e .

# Start the agent
python agent.py dev
The agent requires no .env file. On startup it fetches all API keys (LiveKit, Google, Resemble, STT providers) from the backend dashboard. Make sure the backend is running first and provider keys are configured at API Keys.

​
Troubleshooting

  • Ensure PostgreSQL is running
  • Verify POSTGRES_PASSWORD in the root .env matches your PostgreSQL credentials
  • For Docker: the database takes a few seconds to initialize on first run
  • Ensure the backend is running at the URL specified in NEXT_PUBLIC_API_URL
  • Check CORS: FRONTEND_URL in backend .env should match your frontend URL
  • Ensure the backend is running and all provider keys are configured at API Keys
  • Verify LiveKit credentials are set and the URL uses wss:// protocol
  • Check that at least one STT provider key is configured in the dashboard
  • Check the agent terminal for “Injected N keys from backend dashboard” on startup
  • Ensure PostgreSQL is running and accessible
  • Run alembic upgrade head from the backend/ directory with the venv activated
  • If migrations are out of sync: alembic current shows the current state