English
Quick Start
Self-Hosted

Self-Hosted Quick Start

Run PuppyOne locally.

Prerequisites

Option 1: Docker Compose (recommended)

1. Clone the repository

git clone https://github.com/puppyone-ai/puppyone.git
cd puppyone

2. Configure environment variables

cp .env.example .env

Edit .env and fill in the required values. See the environment variable section below.

3. Start the services

docker compose up --build

4. Access the services

Option 2: Start services manually

1. Clone the repository

git clone https://github.com/puppyone-ai/puppyone.git
cd puppyone

2. Start the backend

cd backend
cp .env.example .env  # configure environment variables
uv sync
uv run uvicorn src.main:app --host 0.0.0.0 --port 9090 --reload --log-level info --no-access-log

3. Start the frontend

cd frontend
cp .env.example .env
npm install
npm run dev

4. Access the services

Environment variables

Key settings in your .env file:

# Supabase (required)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key
SUPABASE_SERVICE_KEY=your-supabase-service-role-key
 
# S3 storage
S3_BUCKET=your-bucket
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
 
# LLM (used for ETL and agent chats)
OPENAI_API_KEY=sk-...
 
# Redis (task queue)
REDIS_URL=redis://localhost:6379

Connect an agent

In a self-hosted setup, your MCP Server URL looks like this:

http://localhost:9090/api/v1/mcp/server/{API_KEY}

Cursor configuration:

{
  "mcpServers": {
    "puppyone-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9090/api/v1/mcp/server/sk_xxx"]
    }
  }
}

Common issues

Port conflicts

Change the ports in docker-compose.yml or in your startup commands.

Database connection failed

Check that SUPABASE_URL and SUPABASE_KEY are configured correctly.

MCP connection failed

Make sure the backend service is running and the API key is valid.

Next steps

CloudCLI Quick Start