Getting Started
Get Voxly running locally in under 5 minutes. You'll need Node.js 18+, Python 3.11+, and PostgreSQL installed.
One-Command Setup
The fastest way to get started is using our CLI tool. It scaffolds the project and handles service orchestration.
# Install the Voxly CLI globaly (or run via npx)
npx voxly create my-agency
# Step into the directory
cd my-agency
# Start EVERYTHING (Backend + Frontend)
voxly dev✓ You're all set!
Visit http://localhost:3000 for the dashboard and http://localhost:8000/docs for the API.
CLI Tools
Voxly comes with a powerful CLI to manage your development and production lifecycle.
voxly create [dir]
Scaffolds a new Voxly instance with guided configuration for AI providers (OpenAI, Gemini, Claude).
voxly dev
The "One-Command" orchestrator. Automatically boots the FastAPI server and Next.js frontend in development mode.
voxly migrate
Triggers Alembic migrations to keep your database schema in sync with the latest updates.
Architecture
Voxly follows a modern fullstack architecture with a FastAPI backend, Next.js frontend, and integrations with GitHub, WhatsApp (Twilio), and Claude AI.
System Flow
GitHub Repos
FastAPI Backend + Claude AI
WhatsApp (Twilio)
Backend Stack
- • FastAPI — REST API framework
- • SQLAlchemy — ORM with PostgreSQL
- • Alembic — Database migrations
- • Anthropic Claude — AI responses
- • Twilio — WhatsApp messaging
- • Redis — Rate limiting & caching
Frontend Stack
- • Next.js 14 — React framework
- • TypeScript — Type-safe code
- • Tailwind CSS — Utility-first CSS
- • Framer Motion — Animations
- • React Query — Data fetching
- • React Hook Form — Form handling
API Reference
Base URL: http://localhost:8000/api/v1
All endpoints require JWT Bearer token unless marked as "Public" or "API Key".
🔐 Authentication
/auth/registerRegister a new userPublic/auth/loginLogin and receive JWT tokenPublic/auth/meGet current user profileJWT/auth/meUpdate profileJWT👥 Clients
/clientsList all clientsJWT/clientsCreate a new clientJWT/clients/:idGet client detailsJWT/clients/:idUpdate clientJWT/clients/:idDelete clientJWT📁 Projects
/projectsList all projectsJWT / API Key/projectsCreate a projectJWT/projects/:idGet project detailsJWT / API Key/projects/:idUpdate projectJWT🎯 Milestones
/projects/:id/milestonesList milestones for a projectJWT/projects/:id/milestonesCreate a milestoneJWT/milestones/:idUpdate milestoneJWT🔑 API Keys
/api_keysList your API keysJWT/api_keysGenerate a new API keyJWT/api_keys/:idRevoke an API keyJWT💳 Billing
/billing/plansList available plansPublic/billing/subscriptionGet current subscriptionJWT/billing/usageGet usage statisticsJWT/billing/checkoutCreate checkout sessionJWT📲 Notifications
/notifications/sendSend custom WhatsApp messageJWTConfiguration
All configuration is done via .env file in the backend/ directory.
DATABASE_URLRequiredPostgreSQL connection stringpostgresql://user:pass@localhost/voxlySECRET_KEYRequiredJWT signing secretyour-super-secret-key-hereANTHROPIC_API_KEYOptionalClaude AI API keysk-ant-...OPENAI_API_KEYOptionalOpenAI API key (for GPT-4o Vision)sk-...GEMINI_API_KEYOptionalGoogle Gemini API keyAIza...TWILIO_ACCOUNT_SIDRequiredTwilio account SIDAC...TWILIO_AUTH_TOKENRequiredTwilio auth tokenyour_auth_tokenTWILIO_WHATSAPP_NUMBERRequiredTwilio WhatsApp numberwhatsapp:+14155238886GITHUB_TOKENOptionalGitHub personal access tokenghp_...REDIS_URLOptionalRedis connection URLredis://localhost:6379STRIPE_SECRET_KEYOptionalStripe secret key for billingsk_test_...RAZORPAY_KEY_IDOptionalRazorpay key ID (Indian billing)rzp_test_...Deployment
Option 1: VPS / Hetzner (Recommended)
Use our automated scripts to set up a production-ready VPS with Nginx, SSL, and Docker.
# 1. SSH into your VPS and run setup
bash <(curl -s https://voxly.dev/install-server.sh)
# 2. Configure your .env and run deployment
./scripts/deploy_voxly.shOption 2: Docker Compose (Self-Hosted)
# Run in production mode
docker-compose -f docker-compose.prod.yml up -dDeployment Architecture
In production, Voxly uses **Nginx** as a reverse proxy to handle SSL termination (via Let's Encrypt) and load balancing between the Next.js frontend and FastAPI backend. All services are containerized for high availability and easy scaling.
Production Checklist
- Set strong SECRET_KEY (32+ chars)
- Configure production DATABASE_URL
- Enable HTTPS on all endpoints
- Set up Stripe/Razorpay webhook URLs
- Configure Twilio production credentials
- Set up Redis for rate limiting
- Enable CORS for your frontend domain
- Set up monitoring and logging
FAQ
Can I use different AI providers?
Yes! Voxly supports a multi-provider "Bring Your Own Key" (BYOK) architecture. You can use Anthropic Claude, OpenAI (GPT-4o), or Google Gemini. Switch providers in your organization settings.
How does Vision support work?
When a client sends a screenshot on WhatsApp, Voxly uses multimodal LLMs (like GPT-4o or Gemini 1.5) to analyze the image, cross-reference it with your GitHub code, and optionally open issues automatically.
Is my client data secure?
Security is our priority. Voxly uses industry-standard JWT for auth, enforces strict Row Level Security (RLS) in the database, and never trains models on your private repository data.
How do I add custom tools?
You can extend Voxly by adding new tool definitions in backend/app/services/ai_providers/tools/. Use the ReAct pattern to let the agent decide when to use them.