Skip to main content
Running px0 locally allows you to test, develop, and integrate prompt management into your application before deploying to production. This guide walks you through setting up px0 with Docker Compose.

​
Prerequisites

Before starting, ensure that Docker and Docker Compose are installed on your machine.

​
Initial Setup

  1. Clone the px0 repository and navigate to the project root directory:
git clone https://github.com/px0-ai/px0.git
cd px0
  1. Copy the example environment file to create your local environment file:
cp .env.example .env
  1. Open the .env file and set the RESEND_API_KEY variable:
RESEND_API_KEY=mock
Setting RESEND_API_KEY to mock bypasses email verification during user registration, automatically marking newly registered users as verified immediately. If you leave RESEND_API_KEY empty or omit it during registration, the Go API server generates a six-digit verification code and prints it to standard output. You will then need to retrieve it from the container logs and verify manually.

​
Orchestration Services

To build the Go application image, run migrations, and start all dependency containers, run the following command in detached mode from the project root: 
docker compose up -d
After starting the services, you can open the px0 Web Console at http://localhost:8000 to navigate and manage your prompt infrastructure, or you can continue directly from your terminal using CLI tools like curl.

​
Port Mapping and Web UIs

When you boot the stack, the following services and endpoints are exposed locally:
ServicePortEndpoint URLDescription
Go API Server8000http://localhost:8000The primary Go backend application built with Fiber
Prometheus9090http://localhost:9090The metrics database scraping all collector endpoints
Grafana3000http://localhost:3000The visualization platform preloaded with provisioned dashboards
OpenTelemetry Collector4317 / 4318localhost:4317The OTLP gRPC and HTTP receiver pipelines
OTEL Prometheus Exporter8889http://localhost:8889Scraper endpoint for Go API server metrics
PostgreSQL Exporter9187http://localhost:9187Scraper endpoint for PostgreSQL database metrics
Redis Exporter9121http://localhost:9121Scraper endpoint for Redis cache metrics

​
Verification and Traffic Generation

Once the containers are running, you can verify the setup by running health checks and registering a user.

​
1. Health Check Request

Send a request to the health endpoint to confirm the API server is healthy: 
curl -i http://localhost:8000/v1/health

​
2. Register a User

Register a new user using a JSON payload. Ensure your password is secure: at least 8 characters, one uppercase letter, one lowercase letter, one digit, and one special character. 
curl -i -X POST http://localhost:8000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "hello@example.com", "password": "SecurePassword123!"}'
If you configured RESEND_API_KEY=mock in your environment file, the user is verified immediately. If you left RESEND_API_KEY empty, retrieve the six-digit code from the container logs: 
docker compose logs app | grep EMAIL
Then, submit the code to verify your account: 
curl -i -X POST http://localhost:8000/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email": "hello@example.com", "code": "<retrieved_code>"}'

​
3. Login to Obtain a Token

Log in to establish a session and obtain your bearer token: 
curl -i -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "hello@example.com", "password": "SecurePassword123!"}'
Copy the token value from the JSON response to use in authenticated requests. This session token starts with sess_.

​
Next Steps

Now that you have running services and a verified account, you can proceed to obtain an API key for programmatic integration, or create and render your first prompt.