Docs
GitHubDiscord

Local Development

Test and debug a local Zoneless instance running in Docker.

Start with the Self-hosting guide. The default Docker setup runs in test mode with simulated USDC.

Local URLs

Test funds

Test mode (LIVEMODE=false, the default) uses simulated USDC. Checkout shows a test wallet you can approve or decline. Payouts stay pending until processed; the dashboard runs build and broadcast for you without a signer. No Solana wallet, faucet, or network is required.

Adding test USDC

  • Open Balance in the dashboard and click Add funds.
  • Enter an amount and click Add test USDC.
  • The funds are credited to your ledger immediately.

You can also credit the ledger with POST /v1/test_helpers/treasury/topups using your platform API key.

Optional: test on-chain with Solana Devnet

To exercise real Devnet transactions instead of simulated funds, set LIVEMODE=false and SETTLEMENT_RAIL=onchain. Then add test SOL from the Solana faucet and test USDC from the Circle faucet (select USDC and Solana Devnet). Do not send real SOL or USDC to a Devnet wallet.

For live mode, follow Fund your platform wallet.

Viewing the database

The local Docker setup includes Mongo Express for viewing MongoDB data.

  • Open localhost:8082 in your browser.
  • Log in with username admin and password admin123.
  • Browse collections to inspect objects created through the API.

Webhooks with Docker

A container cannot reach a webhook handler on your computer through localhost. Use host.docker.internal instead.

See Webhooks for endpoint setup and signature verification.

Webhook URL in Docker
# Instead of this:
http://localhost:4242/webhook

# Use this when running inside Docker:
http://host.docker.internal:4242/webhook

Following API logs

Follow the API container logs while testing requests.

Tail API logs
docker logs --follow zoneless-api

Next steps