Quickstart

Zero to first proxied request in under 5 minutes.

1 Install

Stockyard ships as a single binary. No runtime, no dependencies, no package manager.

# One-line install (Linux / macOS)
curl -fsSL https://stockyard.dev/install.sh | sh

Or download directly:

# Download, make executable, move to PATH
wget https://github.com/stockyard-dev/stockyard/releases/latest/download/stockyard-linux-amd64
chmod +x stockyard-linux-amd64
mv stockyard-linux-amd64 /usr/local/bin/stockyard

Verify the install:

stockyard doctor

This checks your config, data directory, database, port availability, and provider keys. Add --json for machine-readable output.

2 Start

Set a provider key and start the server. Stockyard auto-detects which provider to use from the key prefix.

export OPENAI_API_KEY=sk-...
stockyard

# Listening on :4200
# Proxy: http://localhost:4200/v1  (OpenAI-compatible)
# 76 middleware modules loaded
# Dashboard: http://localhost:4200/ui

3 Send a request

In a second terminal, send a chat completion through the proxy. The API is OpenAI-compatible, so any tool or SDK that speaks OpenAI works unchanged.

curl http://localhost:4200/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

You get a standard OpenAI-format response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello! How can I help you today?"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21}
}

That request just passed through the full middleware chain: rate limiting, cost tracking, prompt logging, failover detection, and more. All of it happened transparently.

4 Verify it’s working

Hit the health endpoint (no auth needed) and the status endpoint (needs your admin key) to confirm everything is running:

# Public health check
curl http://localhost:4200/health
# {"status":"ok"}

# Full platform status (set an admin key first)
export STOCKYARD_ADMIN_KEY=sy_admin_your_secret
curl http://localhost:4200/api/platform/health \
  -H "X-Admin-Key: $STOCKYARD_ADMIN_KEY"
# {"status":"ok","proxy":"healthy","modules":76,"providers":["openai","anthropic",...]}

Open http://localhost:4200/ui for the web console. It shows traces, costs, module status, and provider health in real time. No separate install, no external dependencies.

5 Enable a module

The proxy starts with a default module set. You can toggle individual modules at runtime without restarting.

# Enable response caching (saves money during development)
curl -X PUT http://localhost:4200/api/proxy/modules/cachelayer \
  -H "X-Admin-Key: $STOCKYARD_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Set a daily spending cap
curl -X PUT http://localhost:4200/api/proxy/modules/costcap \
  -H "X-Admin-Key: $STOCKYARD_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "config": {"daily_limit_usd": 5.0}}'

Changes take effect immediately. No restart, no deploy, no config file edit. See Modules & Providers for the full list of 76 available modules.

6 Use your existing SDK

Stockyard is an OpenAI-compatible proxy. Point any OpenAI SDK at it by changing the base URL. That’s the only code change.

# Python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4200/v1",
    api_key="sk-..."   # your real provider key
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

# Node.js
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:4200/v1',
  apiKey: 'sk-...'
});

const res = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }]
});
console.log(res.choices[0].message.content);

7 Add a config file (optional)

For persistent configuration, create stockyard.yaml in your working directory:

# stockyard.yaml
port: 4200
admin_key: "sy_admin_your_secret"

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

modules:
  cachelayer:
    enabled: true
    ttl: 3600
  costcap:
    enabled: true
    daily_limit_usd: 10.00
  promptguard:
    enabled: true
  rateshield:
    enabled: true
    rpm: 60

Environment variables in ${...} syntax are expanded at startup. Never commit API keys directly. See Auth & Config for the full configuration reference.

8 Run with Docker (optional)

If you prefer containers:

docker run -d \
  -p 4200:4200 \
  -e OPENAI_API_KEY=sk-... \
  -e STOCKYARD_ADMIN_KEY=sy_admin_... \
  -v stockyard-data:/data \
  ghcr.io/stockyard-dev/stockyard:latest

OpenTelemetry export (optional)

Send traces to any OTLP-compatible backend (Jaeger, Grafana, Datadog, Honeycomb) with one environment variable:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
stockyard

Every proxied request becomes an OTEL span with attributes for model, provider, tokens, cost, and latency. Spans are batched (100 per batch, 5s flush) and exported as OTLP JSON.

Next steps

You have a working proxy with cost tracking, caching, and the full middleware chain. Here’s where to go from here: