| name | sandbox |
| description | Start or restart the E2E test sandbox (NEAR blockchain + Treasury backend + PostgreSQL). Required before running Playwright E2E tests. |
| argument-hint | [start|stop|restart|status] |
E2E Test Sandbox
Manages the Docker sandbox container needed for Playwright E2E tests. The sandbox provides a local NEAR blockchain, the Treasury backend API, a Sputnik DAO indexer, and PostgreSQL — all in a single container.
Usage
/sandbox or /sandbox start — Start the sandbox (pull latest image, stop conflicts, run)
/sandbox stop — Stop and remove the sandbox container
/sandbox restart — Stop then start
/sandbox status — Check if sandbox is running and healthy
How to start the sandbox
1. Free port 8080
The sandbox needs ports 3030, 8080, and 5001. Stop any conflicting processes first:
lsof -i :8080 -P -n
docker stop nt-be-postgres-1 2>/dev/null || true
kill $(lsof -t -i :8080) 2>/dev/null || true
2. Pull and run the sandbox image
docker pull ghcr.io/near-devhub/trezu/near-treasury-sandbox:main
docker rm -f sandbox 2>/dev/null || true
docker run -d --name sandbox \
-p 3030:3030 -p 8080:8080 -p 5001:5001 \
--health-cmd "curl -f http://localhost:8080/api/health || exit 1" \
--health-interval 10s \
--health-timeout 5s \
--health-retries 30 \
--health-start-period 120s \
ghcr.io/near-devhub/trezu/near-treasury-sandbox:main
3. Wait for the sandbox to be healthy
The sandbox takes 60-120 seconds to fully initialize (NEAR blockchain genesis, contract deployment, database migrations).
echo "Waiting for sandbox to be healthy..."
for i in $(seq 1 60); do
if curl -sf http://localhost:8080/api/health > /dev/null 2>&1; then
echo "Sandbox is ready!"
break
fi
echo "Attempt $i: Not ready yet..."
sleep 5
done
Verify with:
curl -s http://localhost:8080/api/health
docker inspect sandbox --format='{{.State.Health.Status}}'
4. Run E2E tests
cd nt-fe
BACKEND_URL=http://localhost:8080 npx playwright test
How to stop the sandbox
docker stop sandbox && docker rm sandbox
Ports
| Port | Service | Description |
|---|
| 3030 | NEAR RPC | Local NEAR blockchain JSON-RPC |
| 8080 | Treasury API | Backend REST API |
| 5001 | Sputnik Indexer | DAO proposal caching |
Image
The sandbox image is built automatically by CI and pushed to:
ghcr.io/near-devhub/trezu/near-treasury-sandbox:main
PR-specific images are tagged as pr-<number> when available.
Troubleshooting
- Container won't start: Check
docker logs sandbox for errors
- API returns 500: Services need 60-120s to initialize after container start
- Port conflict: Stop the dev backend (
nt-be-postgres-1) or any process on port 8080