Getting Started

Quick start guide and initial setup

Getting Started

Prerequisites

• Node.js 20+ installed
• Docker and Docker Compose (for deployment)
• Supabase account and project
• ActivePieces instance (self-hosted or cloud)
• OpenAI or Anthropic API key

Installation

1. Clone the Repository

git clone https://github.com/your-org/agency-os.git
cd agency-os

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env.local file:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_secret_key

# AI Services
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# ActivePieces
NEXT_PUBLIC_ACTIVEPIECES_URL=your_activepieces_url
ACTIVEPIECES_API_KEY=your_api_key

# Optional
BANNERBEAR_API_KEY=your_bannerbear_key

4. Set Up Database

Run the Supabase migrations:

npm run migrate

5. Start Development Server

npm run dev

Visit http://localhost:3000 to see your application.

First Steps

1. Create Your First Signal

Navigate to the Engine Room interface:

• Click "New Signal"
• Enter signal details (name, description, category)
• Configure ActivePieces flow ID
• Define input/output schemas
• Save the signal

2. Set Up a Campaign

In the Engine Room:

• Click "New Campaign"
• Select a signal
• Configure campaign parameters
• Set schedule (if recurring)
• Save as draft

3. Use Directors Console

Switch to Directors Console:

• Enter natural language intent (e.g., "Create a LinkedIn post about our new product")
• Review the generated execution plan
• Approve or modify steps
• Execute the plan
• Monitor progress in real-time

4. Monitor Executions

Switch to Monitoring Dashboard:

• View execution history
• Check generated artifacts
• Review performance metrics
• Investigate any errors

Development Workflow

Running Tests

npm test

Type Checking

npm run type-check

Linting

npm run lint
npm run lint:fix

Code Formatting

npm run format
npm run format:check

Deployment

Docker Deployment

Build the production image:

docker build -f Dockerfile.prod -t agency-os .

Run with Docker Compose:

docker-compose -f docker-compose.prod.yml up -d

Environment Configuration

For production, create .env.production with production values.

Health Checks

The application includes health check endpoints:

• /api/health - Application health
• /api/health/db - Database connectivity

Troubleshooting

Common Issues

Database Connection Errors

• Verify Supabase credentials
• Check network connectivity
• Ensure database migrations are applied

ActivePieces Integration Issues

• Verify API key is correct
• Check ActivePieces URL is accessible
• Ensure flows are published

Build Failures

• Clear .next directory
• Delete node_modules and reinstall
• Check TypeScript errors with npm run type-check

Next Steps

• Read the Architecture documentation
• Learn about Directors Console features
• Explore Engine Room capabilities
• Review the Whitepaper for philosophical context