30-Minute Full Setup

Run ACP locally with full control. This guide covers the complete stack: Next.js frontend, Python API engine, Cloudflare Worker, and all supporting infrastructure.

Prerequisites

Make sure you have the following installed before proceeding:

Step 1: Clone the repository

git clone <repository-url>
cd ACP-PROJECT

This gives you the core repository containing the frontend, Worker source, Python engine, axiom data, and all configuration files.

Step 2: Set up environment variables

Copy the example environment file and fill in your API keys:

# Copy example env file
cp .env.example .env

# Edit .env with your API keys:
# - OPENROUTER_API_KEY (required)
# - DATABASE_URL (optional, for frontend auth)

At minimum, your .env file needs:

OPENROUTER_API_KEY=your_key_here
WORKER_URL=https://your-worker.workers.dev

Step 3: Install dependencies

Frontend (Next.js)

# Navigate to the frontend directory
# cd frontend/acp-web (see archive/frontend/)
npm install

Python core (optional)

# From the project root
pip install -r requirements.txt

The Python dependencies include FastAPI, SQLAlchemy, and the LLM adapter libraries. A virtual environment is recommended:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step 4: Run the application

Choose the option that matches your needs:

Option A: Frontend only (recommended for getting started)

This is the fastest way to get a running application. The frontend communicates directly with the deployed Worker API.

# cd frontend/acp-web (see archive/frontend/)
npm run dev

Visit http://localhost:3000 in your browser.

Option B: Full stack (with Python API)

Run both the Python API engine and the Next.js frontend. You will need two terminal windows.

# From project root
uvicorn main:app --reload --port 8000

# cd frontend/acp-web (see archive/frontend/)
npm run dev

Option C: Docker Compose (everything at once)

If you have Docker installed, you can start the entire stack with a single command:

docker-compose up

This starts the frontend, Python API, PostgreSQL, and Redis automatically with the correct networking.

Step 5: Verify installation

Health check

curl http://localhost:3000/api/health
# Should return: {"status":"ok"}

Test consensus

1. Visit http://localhost:3000/dashboard
2. Enter a question in the input field
3. Click Run Consensus
4. Watch the D-score converge in real time

Step 6: Explore the ecosystem

ACP consists of three repositories that work together. The diagram below shows how they relate:

+---------------------+
|   ACP-PROJECT       |  <-- You are here (execution)
|   - Frontend (UI)   |
|   - Worker (API)    |
|   - Python Engine   |
+---------------------+
           |
           +---> ACP-DATASETS (verified axioms)
           |
           +---> ACP-PROMPTS (system prompts)

Clone the companion repositories into the same parent directory to enable the full feature set:

Troubleshooting

"Vectorize not available"

Problem: The health endpoint shows axioms_seeded: false.

Solution: Seed the vector database with axiom embeddings:

cd workers/cloudflare-worker
CLOUDFLARE_API_TOKEN=your_token node ../../scripts/vectorize/seed-all-axioms.js

"API key invalid"

Problem: Getting authentication errors from the Worker API.

Solution: Verify your OpenRouter key is valid:

# Test OpenRouter key
curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

# Should return a list of available models

"Database connection failed"

Problem: Frontend cannot connect to PostgreSQL.

Solution: Install PostgreSQL, configure the connection string, and run migrations:

# Add to your .env file:
# DATABASE_URL="postgresql://user:password@localhost:5432/acp"

# Then run migrations:
# cd frontend/acp-web (see archive/frontend/)
npx prisma migrate dev

"Module not found"

Problem: Import errors when running the frontend.

Solution: Clear the dependency cache and reinstall:

# cd frontend/acp-web (see archive/frontend/)
rm -rf node_modules package-lock.json
npm install

"Worker timeout"

Problem: Consensus requests are timing out.

Solution: Reduce the iteration count or use faster models:

{
  "max_iterations": 3,
  "models": ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]
}

Next steps

• Core Protocol -- understand the philosophical foundation, axiom levels, and φ-convergence mathematics behind ACP.
• Ecosystem -- deep dive into the three-repository architecture and how the components interact.
• API Reference -- complete documentation for all Worker and Python API endpoints.
• Use Cases -- real-world applications of ACP for fact-checking, code review, content moderation, and research synthesis.
• Self-Hosting Guide -- deploy your own ACP Worker on Cloudflare for production use.