freeride

FreeRide

FreeRide is a local gateway running on http://localhost:11343. It accepts the OpenAI Chat Completions API and forwards to whichever free-tier provider the user has keys for, failing over across providers and keys when one rate limits or errors.

This skill teaches you (the agent) how to detect FreeRide, wire any OpenAI-shaped client against it, diagnose failures, and use its CLI.

Detect that FreeRide is running

In order, cheapest first:

1. Health check — curl -s http://localhost:11343/health. Returns {"ok": true, "version": "0.x.y", "providers": [...]} when up.
2. Process check — lsof -iTCP:11343 -sTCP:LISTEN -n -P 2>/dev/null or ss -tlnp | grep 11343 on Linux.
3. Config presence — ~/.freeride/config.json exists (means FreeRide was installed even if not currently running).

The port 11343 is hard-coded — FreeRide refuses to auto-pick a different port because agent configs (Aider's OPENAI_API_BASE, Continue's apiBase, etc.) are written against this exact value.

Wire any OpenAI-shaped client against it

export OPENAI_API_BASE=http://localhost:11343/v1
export OPENAI_API_KEY=any

The API key value is irrelevant — FreeRide doesn't authenticate inbound requests; it uses the user's real provider keys (which it reads from env vars like OPENROUTER_API_KEY) for outbound calls. Setting any, unused, or any literal string works.

Python (openai SDK)

from openai import OpenAI
client = OpenAI(base_url="http://localhost:11343/v1", api_key="any")
resp = client.chat.completions.create(
    model="openrouter/free",  # or any model from /v1/models
    messages=[{"role": "user", "content": "hello"}],
)

curl

curl http://localhost:11343/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "openrouter/free", "messages": [{"role": "user", "content": "hi"}]}'

Streaming

"stream": true works. Server emits text/event-stream with data: {...} chunks and a final data: [DONE]. The first chunk is buffered until upstream confirms the stream is real — if upstream fails before the first chunk, FreeRide retries on the next provider/key transparently. After the first chunk has shipped, mid-stream errors propagate as a truncated stream.