Runcycles Server

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

Quick Start

One-command quickstart (recommended)

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.

Docker (server only)

# 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

Pre-built image (no source code needed)

# 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.

Manual build

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.24.jar

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

Architecture

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/):

Module	Purpose
cycles-protocol-service-model	Shared request/response POJOs
cycles-protocol-service-data	Redis repository + Lua scripts
cycles-protocol-service-api	Spring Boot controllers + auth

API Endpoints

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

Endpoint	Method	Description
/v1/decide	POST	Evaluate budget decision without reserving
/v1/reservations	POST	Create budget reservation
/v1/reservations	GET	List reservations (with pagination/filters)
/v1/reservations/{id}	GET	Fetch a single reservation
/v1/reservations/{id}/commit	POST	Record actual spend
/v1/reservations/{id}/release	POST	Return reserved budget
/v1/reservations/{id}/extend	POST	Extend reservation TTL
/v1/events	POST	Direct debit without prior reservation (returns 201)
/v1/balances	GET	Query budget balances for scopes

Build

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.24.jar.

Docker Deployment

Two Docker Compose files are provided for different use cases:

File	Use case	Command
docker-compose.yml	Development — builds from source inside Docker (multi-stage build, no local Java/Maven needed)	docker compose up --build
docker-compose.prod.yml	Production / end-user — pulls pre-built image from GHCR	docker compose -f docker-compose.prod.yml up

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

Container images

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

Testing

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.

Configuration

Variable	Default	Description
REDIS_HOST	localhost	Redis hostname
REDIS_PORT	6379	Redis port
REDIS_PASSWORD	(empty)	Redis password
cycles.expiry.interval-ms	5000	Background expiry sweep interval (ms)

Documentation

• Cycles Documentation — full docs site
• Deploy the Full Stack — deployment guide with server setup
• Server Configuration Reference — all server configuration options
• cycles-protocol-service/README.md — core concepts, authentication, error codes, and the Redis data model