Reference implementation of the Cycles Budget Authority API (v0.1.23) — a reservation-based budget control service for AI agents and workflows.

Starts the full stack (Redis + Cycles Server + Admin Server), creates a tenant, API key, and budget, and verifies the full reserve/commit lifecycle:

./quickstart.sh

Prerequisites: Docker and Docker Compose v2+. No Java or Maven required.

# Build from source and start (no local Java/Maven required)
docker compose up --build

Server starts on port 7878. Interactive API docs: http://localhost:7878/swagger-ui.html

# Download docker-compose.prod.yml, then:
docker compose -f docker-compose.prod.yml up

This pulls the latest image from ghcr.io/runcycles/cycles-server.

Prerequisites: Java 21+, Maven, Docker (for Redis)

# 1. Start Redis
docker run -d -p 6379:6379 redis:7-alpine

# 2. Build
cd cycles-protocol-service
./build-all.sh

# 3. Seed a sample budget
./init-budgets.sh

# 4. Run
REDIS_HOST=localhost REDIS_PORT=6379 \
  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.23.jar

Server starts on port 7878. Interactive API docs: http://localhost:7878/swagger-ui.html

HTTP client
    │  X-Cycles-API-Key
    ▼
Spring Boot 3.5 (port 7878)
    │  ApiKeyAuthenticationFilter
    │  Controllers → Repository
    ▼
Redis 7+  (Lua scripts for atomicity)

Modules (under cycles-protocol-service/):

All endpoints require X-Cycles-API-Key header authentication.

All commands run from the cycles-protocol-service/ directory.

cd cycles-protocol-service

# Full build (compile + unit tests + package)
mvn clean install

# Or use the wrapper script
./build-all.sh

The fat JAR is produced at cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.23.jar.

Two Docker Compose files are provided for different use cases:

Both start Redis 7 and the cycles-server on port 7878.

Pre-built images are published to GitHub Container Registry on each release:

ghcr.io/runcycles/cycles-server:latest
ghcr.io/runcycles/cycles-server:<version>    # e.g. 0.1.23

cd cycles-protocol-service

# Unit tests only (no Docker required)
mvn test

# Unit + integration tests (requires Docker for Testcontainers Redis)
mvn clean install -Pintegration-tests

Integration tests (*IntegrationTest.java) use Testcontainers to spin up a Redis instance automatically. They are excluded from the default build and enabled via the -Pintegration-tests Maven profile.

See cycles-protocol-service/README.md for full documentation including core concepts, authentication, error codes, and the Redis data model.