Restack boilerplate

This project uses Restack, the open source AI agent orchestration at enterprise scale.

Motivation

Restack has helped enterprise companies build AI agents at large scale where product teams often sit between domain experts (customer service, marketing, sales) and engineering teams.

• The challenge: product teams wants to iterate quickly with domain experts to craft agent behavior and experience. But every change requires engineering coordination, creating bottlenecks that slow innovation.

• Restack approach: empowers product teams with full autonomy from engineering. Product collaborates directly with domain experts to refine agent behavior. Engineering focuses on what they do best: building reliable integrations with 99.99% SLAs.

Built on Python + Kubernetes because enterprises already run AI workloads this way. Works with your existing infrastructure and team expertise.

Quick start

cp .env.example .env

• Set RESTACK_ENGINE_MCP_ADDRESS for ngrok tunnel with ngrok http 11233

First time setup

pnpm localsetup

This installs dependencies, starts infrastructure (PostgreSQL, ClickHouse, Restack), and runs migrations. To seed the admin workspace (admin user, build agent, templates), set ADMIN_SEED=true before starting the backend, or run pnpm db:admin:insert after migrations.

Start development

pnpm localdev

This starts infrastructure and all dev servers with hot reloading without resetting your database.

Manual setup (if you prefer step-by-step)

# Install dependencies
pnpm install

# Start infrastructure (PostgreSQL, ClickHouse, Restack)
pnpm infra:start

# Wait for services to be ready, then run migrations
pnpm db:migrate

# Optionally seed admin workspace (admin user, build agent, templates)
pnpm db:admin:insert

# Start all dev servers
pnpm dev

Access your platform

• Agent Orchestration: http://localhost:3000
• Developer Tracing: http://localhost:5233
• API: http://localhost:8000
• ClickHouse: http://localhost:8123 (metrics and analytics)

Default admin (seed user)

The admin seed creates a single platform user you can log in with:

• Email: admin@example.com
• Password: Generated when the admin workspace is first created; it is printed once in the terminal when you run pnpm db:admin:insert and the admin workspace does not exist.

If you never saw the password (e.g. you ran db:admin:insert after the workspace already existed), or you get errors like “no admin in the db” when creating users or using the app:

1. Use the same database as the app: set DATABASE_URL in your environment (e.g. from .env) when running commands.
2. Set a new password (it is logged so you can save it): run pnpm db:admin:password. The new password is printed in the terminal—save it. To choose the password yourself: pnpm db:admin:password -- mypassword.
3. If you need a full reset (clear admin workspace and re-seed from scratch): run pnpm db:admin:reset. The new admin password is printed in the log—save it.
4. Log in at http://localhost:3000 with admin@example.com and that password.

Performance tip: development mode uses hot reloading. For faster page loads, use pnpm build && pnpm start instead of pnpm localdev.

What can you build?

• Customer Support Agents (Zendesk, Intercom, Slack)
  Engineering connects support platforms. Product teams iterate on escalation rules, response tone, and handoff triggers.

• Product Intelligence Agents (PostHog, Linear, Slack)
  Engineering builds analytics and project management pipelines. Product teams adjust feature prioritization logic and user feedback analysis.

• DevOps Monitoring Agents (Sentry, Datadog, Kubernetes, GitHub, OpenAI Codex)
  Engineering integrates monitoring and development tools. Product teams define alert thresholds, incident response workflows, and automated troubleshooting.

• Performance Marketing Agents (Google Ads, Facebook Ads, PostHog, Slack)
  Engineering establishes advertising and analytics connections. Product teams optimize campaign strategies, bidding algorithms, and performance reporting.

• Sales Intelligence Agents (Salesforce, HubSpot, Slack)
  Engineering connects CRM and communication platforms. Product teams refine lead scoring, follow-up sequences, and sales forecasting models.

Platform architecture

• Product interface: web-based agent management with version control, testing playground, and deployment controls. Product teams change agent behavior without code dependencies.

• Engineering infrastructure: python-based integration layer with Temporal workflow orchestration. Kubernetes deployment with enterprise-grade reliability and observability.

• Integration protocol: Model Context Protocol automatically exposes Python functions as agent tools, enabling seamless tool discovery and use across agent workflows.

┌─────────────────────────────────────┐
│       Agent Orchestration           │
│  ┌─────────────┐  ┌─────────────┐   │    ┌─────────────────┐
│  │  Frontend   │◄─│   Backend   │◄──┼────┤  MCP Server     │
│  │  (Next.js)  │  │ (Restack.py)│   │    │  (Integrations) │
│  └─────────────┘  └─────────────┘   │    └─────────────────┘
└─────────────────────────────────────┘             │
                                                    ▼
                                           ┌─────────────────┐
                                           │ External APIs   │
                                           │ (Zendesk, etc.) │
                                           └─────────────────┘

OpenAI setup

This boilerplate uses OpenAI's response API for tool execution. OpenAI API keys are typically configured per-workspace. You'll need:

1. Public MCP URL - For OpenAI to call your local tools (e.g. ngrok)

Mcp server public access

OpenAI needs a public URL to call your MCP server tools:

# Install ngrok (if not installed)
brew install ngrok  # or download from https://ngrok.com

# Expose MCP server
ngrok http 11233

# Add the ngrok URL to .env:
RESTACK_ENGINE_MCP_ADDRESS=https://your-ngrok-url.ngrok-free.app/mcp

Getting started tutorial

Step 1: Try the platform

1. Open Agent Orchestration at http://localhost:3000
2. Login with admin user (after seeding): admin@example.com — the password is generated when you run the admin seed and printed once; save it.
3. Create a workspace, then go to Build to describe what you want or pick a template
4. Go to "Agents" to manage agents; use "Deploy" on an agent for deployment options

Step 2: Give an agent a new task

1. Select the "Customer Support" agent
2. Click "Create Task" and describe an issue: "Customer can't log in to mobile app"
3. Watch the agent analyze the problem and suggest solutions
4. See how it uses tools like Zendesk and knowledge base

Step 3: Test agent improvements (no engineering required)

1. Click "Edit Agent" to change instructions
2. Try: "Always ask for the customer's device type before troubleshooting"
3. Open the Playground to test your changes
4. Send the same login issue and see the improved response
5. Click "Publish Version" to make it live

This workflow demonstrates the product-engineering partnership: product teams can iterate on agent behavior without touching code.

Adding custom integrations

Build integrations in the MCP Server using Restack workflows with Pydantic types. Each function needs both a workflow and function definition to become an agent tool.

Example: Zendesk integration (mock included)

# apps/mcp_server/src/functions/zendesk.py
from pydantic import BaseModel

class SearchTicketsInput(BaseModel):
    query: str

class TicketResult(BaseModel):
    id: str
    subject: str
    status: str

async def search_zendesk_tickets(input: SearchTicketsInput) -> list[TicketResult]:
    """Search Zendesk tickets by query"""
    # Mock implementation included for development
    return [
        TicketResult(id="12345", subject="Login issues", status="open"),
        TicketResult(id="12346", subject="Mobile app crash", status="pending")
    ]

# apps/mcp_server/src/workflows/zendesk.py
from restack_ai import workflow

@workflow.defn(name="search_zendesk_tickets")
class SearchZendeskTicketsWorkflow:
    @workflow.run
    async def run(self, input: SearchTicketsInput) -> list[TicketResult]:
        return await workflow.step(search_zendesk_tickets, input)

How it works

1. Create function with Pydantic types in apps/mcp_server/src/functions/
2. Create matching workflow in apps/mcp_server/src/workflows/
3. The MCP server auto-discovers workflows as agent tools
4. Test in the playground, no restart needed

See apps/mcp_server/README.md for more integration examples.

Production deployment

Option 1: Self-hosted Kubernetes (Enterprise)

Deploy on your own Kubernetes cluster:

# Add Restack Helm repository
helm repo add restack https://github.com/restackio/helm

# Deploy with your configuration
helm install restack restack/restack -f values.yaml

See Restack Helm Charts for full configuration options.

Option 2: Restack Cloud (recommended)

Fully managed infrastructure:

1. Sign up at console.restack.io
2. Deploy your agent workflows
3. Connect your frontend to the managed backend

Option 3: Hybrid (frontend + cloud backend)

Frontend (Vercel)

1. Connect your GitHub repo to Vercel
2. Set build settings:
   • Root Directory: apps/frontend
   • Build Command: turbo run build --filter=boilerplate-frontend

Backend (Restack Cloud)

• Deploy backend and MCP server to Restack Cloud
• Update frontend environment variables to point to cloud endpoints

Option 4: Self-hosted Docker (Hobbyist)

# Production with Docker Compose
pnpm prod:up

# Or build and run locally
pnpm build
pnpm start

Server Actions (Next.js): If you see Failed to find Server Action, set NEXT_SERVER_ACTIONS_ENCRYPTION_KEY in your environment (see .env.example). Generate a key with node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" and set it at build time so all instances use the same key.

Platform management

# Quick commands
pnpm localsetup          # First time setup (install, infra, migrations)
pnpm localdev            # Start infrastructure + dev servers
pnpm dev                 # Start all dev servers with hot reloading (infra must be running)

# Infrastructure management
pnpm infra:start         # Start infrastructure (PostgreSQL, ClickHouse, Restack)
pnpm infra:stop          # Stop infrastructure
pnpm infra:restart       # Restart infrastructure services
pnpm infra:logs          # View container logs
pnpm infra:ps            # Check service status
pnpm infra:reset         # Complete infrastructure reset (⚠️ destroys data)

# Database operations
pnpm db:migrate          # Run database migrations (uses localhost by default)
pnpm db:reset            # Wipe all DB data and re-run migrations (⚠️ destroys data)
pnpm postgres:connect    # Connect to PostgreSQL
pnpm clickhouse:connect  # Connect to ClickHouse

# Production (self-hosted Docker)
pnpm build               # Build for production
pnpm prod:up             # Start production services
pnpm prod:down           # Stop production services
pnpm prod:logs           # View production logs
pnpm prod:restart        # Restart production services (backend, mcp, webhook)
pnpm prod:reset          # Full production reset (⚠️ destroys data)

For developers

Want to contribute or change the platform? See CONTRIBUTING.md for:

• Development setup with hot reloading
• Architecture deep-dive
• Testing and debugging
• Code contribution guidelines

Learn more

• Restack Documentation
• Model Context Protocol

📄 License

Licensed under the Apache License, Version 2.0.