Quickstart

Overview

This quickstart guide will help you launch a complete local CoW Protocol environment using Docker Compose. You’ll have a full stack including orderbook, autopilot, driver, solver, and a forked blockchain ready for testing and development.

The playground runs in fork mode, meaning it forks a live network (like Ethereum mainnet) using a local Anvil node. This gives you access to real token contracts and liquidity while maintaining an isolated testing environment.

Prerequisites

Before you begin, ensure you have the following installed:

Docker & Docker Compose

Install Docker Desktop or Docker Engine with Docker Compose plugin.Verify installation:

docker --version
docker compose version

Rust Toolchain (Optional)

Only needed if you want to modify and rebuild the services locally. Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly

RPC Endpoint

You’ll need an Ethereum RPC endpoint. For optimal performance, use a local node like Reth.Alternatively, use a provider like:

Alchemy
Infura
Tenderly
Public endpoints from Chainlist

RPC demand is very high. Free tier RPC endpoints may rate-limit or perform poorly. A local node or paid plan is strongly recommended for the best experience.

Setup Instructions

Clone the Repository

git clone https://github.com/cowprotocol/services.git
cd services

Configure Environment Variables

Copy the example environment file and edit it with your RPC endpoint:

cd playground
cp .env.example .env

Edit .env and set your RPC URL:

.env

ENV=local
ETH_RPC_URL=wss://mainnet.gateway.tenderly.co  # Replace with your RPC
ACCOUNT_BALANCES=max
POSTGRES_USER=postgres
POSTGRES_PASSWORD=123
TOML_TRACE_ERROR=1
CHAIN=1  # 1=Mainnet, 100=Gnosis, 42161=Arbitrum, 8453=Base
SOURCIFY_MODE=cloud

Chain IDs: Mainnet (1), Gnosis (100), Arbitrum (42161), Base (8453), Polygon (137)

Launch the Playground

Start all services with Docker Compose:

docker compose -f docker-compose.fork.yml up --build

Linux
macOS / Windows

Use the standard fork compose file with live reload:

docker compose -f docker-compose.fork.yml up --build

Use the non-interactive version for better performance:

docker compose -f docker-compose.non-interactive.yml up --build

Due to Docker mount performance on non-Linux platforms, the non-interactive version disables live reload to avoid slow builds.

Limit Services (Optional)You can start only specific services:

docker compose -f docker-compose.fork.yml up --build driver autopilot orderbook

The first build will take several minutes as it compiles all Rust services.

Wait for Services to Start

Monitor the logs until you see:

orderbook - “Starting API server on 0.0.0.0:80”
autopilot - “Starting autopilot”
driver - “Starting driver”
baseline - “Solver ready”

The services will automatically watch for code changes and rebuild when needed (Linux only).

Access Services

Once the playground is running, you can access the following services:

CoW Swap UI

http://localhost:8000The main trading interface for placing orders

CoW Explorer

http://localhost:8001View transaction history and order status

Orderbook API

http://localhost:8080HTTP API for order submission and queries

Adminer (Database UI)

http://localhost:8082Browse the PostgreSQL database

Server: postgres
User: postgres
Password: 123
Database: api

Otterscan (Block Explorer)

http://localhost:8003Local block explorer with transaction traces

Anvil RPC

http://localhost:8545Local forked Ethereum node endpoint

Configure Your Wallet

To interact with CoW Swap, configure your web3 wallet to use the local network:

Rabby Wallet (Recommended)
MetaMask

Install Rabby Wallet
Add a custom network:
- RPC URL: http://localhost:8545
- Chain ID: 1 (or your configured chain)
Import a test account using one of the private keys below
Connect to CoW Swap at http://localhost:8000

MetaMask doesn’t allow changing the mainnet RPC in the UI. Use the browser console:

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x1',
    chainName: 'Local Network (Mainnet)',
    rpcUrls: ['http://localhost:8545'],
    nativeCurrency: {
      name: "Ethereum",
      symbol: "ETH",
      decimals: 18,
    },
  }],
});

Then import a test account private key.

Test Accounts

The playground uses a well-known test mnemonic. All accounts start with 10,000 ETH:

Mnemonic: test test test test test test test test test test test junk
Derivation: m/44'/60'/0'/0/

Private Keys:

(0) 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
(1) 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d
(2) 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a
(3) 0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6

NEVER use these accounts on real networks! These are publicly known test keys for local development only.

Submit Your First Order

Wrap ETH to WETH

CoW Protocol trades ERC-20 tokens. Wrap some ETH first:

Go to http://localhost:8000
Connect your wallet (select the local network)
Click “Wrap” in the interface
Wrap some ETH (e.g., 1 ETH)

Place a Swap Order

Select tokens to swap (e.g., WETH → USDC)
Enter an amount
Review the quote from the orderbook
Sign and submit the order
Wait for the order to be included in an auction

Monitor the Auction

Watch the service logs to see the order lifecycle:

# In the terminal where docker compose is running
# You'll see logs from autopilot, driver, and baseline

Orderbook: Receives and validates the order
Autopilot: Includes the order in the next auction (~12-15 seconds)
Driver + Solver: Compute the best execution
Driver: Submits the winning solution on-chain
Anvil: Mines the settlement transaction

View in Explorer

Check the settlement in:

CoW Explorer: http://localhost:8001
Otterscan: http://localhost:8003 (view full transaction traces)

Resetting the Playground

To reset the entire environment:

Stop and Remove Containers

docker compose -f docker-compose.fork.yml down --remove-orphans --volumes

Reset Your Wallet

Clear pending transactions to avoid nonce issues:

Rabby: Settings → “Clear pending” (More section)
MetaMask: Settings → Advanced → Reset Account

Restart

docker compose -f docker-compose.fork.yml up --build

Switching Networks

To test on a different network (e.g., Gnosis Chain):

Edit playground/.env:

ETH_RPC_URL=https://rpc.gnosischain.com  # Or your Gnosis RPC
CHAIN=100

Reset and restart:

docker compose -f docker-compose.fork.yml down --remove-orphans --volumes
docker compose -f docker-compose.fork.yml up --build

Update your wallet to the new chain ID

Next Steps

Architecture

Learn how the services work together

API Reference

Explore the Orderbook API

Development Guide

Set up for service development

Testing

Run unit and E2E tests

Troubleshooting

Services fail to start

Check that Docker has enough resources (at least 4GB RAM)
Verify your RPC endpoint is accessible
Look for error messages in the logs
Try rebuilding: docker compose -f docker-compose.fork.yml up --build --force-recreate

Slow compilation on macOS/Windows

Use the non-interactive compose file:

docker compose -f docker-compose.non-interactive.yml up --build

This disables live reload which can be slow on non-Linux platforms.

Orders not settling

Check that you wrapped ETH to WETH first
Ensure your token has sufficient balance and approval
Watch the autopilot logs for auction creation
Verify the solver found a valid solution

RPC rate limiting

If you see RPC errors in the logs:

Use a local node (Reth, Geth, etc.) for best performance
Upgrade to a paid RPC plan
Reduce the RPC load by disabling some services

Wallet nonce issues

After resetting the playground, always reset your wallet’s pending transactions:

Rabby: “Clear pending”
MetaMask: “Reset Account”

For more detailed development instructions, see the Development Setup guide.

Get Started

Core Services

Development

Deployment

Overview

Prerequisites

Setup Instructions

Access Services

CoW Swap UI

CoW Explorer

Orderbook API

Adminer (Database UI)

Otterscan (Block Explorer)

Anvil RPC

Configure Your Wallet

Test Accounts

Submit Your First Order

Resetting the Playground

Switching Networks

Next Steps

Architecture

API Reference

Development Guide

Testing

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Services

Development

Deployment

​Overview

​Prerequisites

​Setup Instructions

​Access Services

CoW Swap UI

CoW Explorer

Orderbook API

Adminer (Database UI)

Otterscan (Block Explorer)

Anvil RPC

​Configure Your Wallet

​Test Accounts

​Submit Your First Order

​Resetting the Playground

​Switching Networks

​Next Steps

Architecture

API Reference

Development Guide

Testing

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Prerequisites

Setup Instructions

Access Services

Configure Your Wallet

Test Accounts

Submit Your First Order

Resetting the Playground

Switching Networks

Next Steps

Troubleshooting