Getting Started

Prerequisites

Docker and Docker Compose
AWS credentials (for Bedrock provider)
Anthropic API key (for Anthropic provider)

Installation

Clone the repository:


git clone https://github.com/your-org/convoy.git
cd convoy

Copy the environment file:


cp .env.example .env

Configure your provider credentials in .env (see Configuration)
Start the services:


docker compose up -d

Verify it’s running:


curl http://localhost:8000/health

Response:


{"status": "ok"}

Submit Your First Request


curl -X POST http://localhost:8000/cargo/load \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "model": "claude-sonnet-4-5",
      "max_tokens": 100,
      "messages": [{"role": "user", "content": "Say hello"}]
    },
    "callback_url": "https://your-server.com/callback"
  }'

Track Your Request


curl http://localhost:8000/cargo/{cargo_id}/tracking

Access Points

Service	URL
Convoy API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
Temporal UI	http://localhost:8080

Stop Services


docker compose down

Run Tests


docker compose --profile tests run --rm convoy-tests