Local Development with Docker/Podman¶

Run stdapi.ai locally for development, testing, and evaluation using the free community container image (AGPL-3.0). Full API compatibility — the same endpoints and features as the production deployment.

Run It¶

With AWS credentials (after aws sso login):

docker run --rm -p 8000:8000 \
  --user "$(id -u):$(id -g)" -e HOME=/home/nonroot \
  -v ~/.aws:/home/nonroot/.aws:ro \
  -e AWS_PROFILE=your-profile \
  -e AWS_BEDROCK_REGIONS=us-east-1,us-west-2 \
  -e ENABLE_DOCS=true \
  ghcr.io/stdapi-ai/stdapi.ai-community:latest

Drop -e AWS_PROFILE if your credentials are in the default profile: the container reads the mounted ~/.aws under whichever profile that variable names, and a session created by aws sso login --profile your-profile lives under that name.

With environment variables instead:

docker run --rm -p 8000:8000 \
  -e AWS_ACCESS_KEY_ID=your-access-key-id \
  -e AWS_SECRET_ACCESS_KEY=your-secret-access-key \
  -e AWS_SESSION_TOKEN=your-session-token \
  -e AWS_BEDROCK_REGIONS=us-east-1,us-west-2 \
  -e ENABLE_DOCS=true \
  ghcr.io/stdapi-ai/stdapi.ai-community:latest

podman run --rm -p 8000:8000 \
  --userns=keep-id:uid=65532,gid=65532 \
  -v ~/.aws:/home/nonroot/.aws:ro,z \
  -e AWS_PROFILE=your-profile \
  -e AWS_BEDROCK_REGIONS=us-east-1,us-west-2 \
  -e ENABLE_DOCS=true \
  ghcr.io/stdapi-ai/stdapi.ai-community:latest

%%{init: {'flowchart': {'htmlLabels': true}} }%%
flowchart LR
  openai["<img src='../styles/logo_openai.svg' style='height:64px;width:auto;vertical-align:middle;' /> OpenAI SDK"] --> local["<img src='../styles/logo.svg' style='height:64px;width:auto;vertical-align:middle;' /> stdapi.ai (community)<br/>Docker/Podman"]
  anthropic["<img src='../styles/logo_anthropic.svg' style='height:64px;width:auto;vertical-align:middle;' /> Anthropic SDK"] --> local
  local --> bedrock["<img src='../styles/logo_amazon_bedrock.svg' style='height:64px;width:auto;vertical-align:middle;' /> Amazon Bedrock"]
  local --> polly["<img src='../styles/logo_amazon_polly.svg' style='height:64px;width:auto;vertical-align:middle;' /> Amazon Polly"]
  local --> transcribe["<img src='../styles/logo_amazon_transcribe.svg' style='height:64px;width:auto;vertical-align:middle;' /> Amazon Transcribe"]
  local --> s3["<img src='../styles/logo_amazon_s3.svg' style='height:64px;width:auto;vertical-align:middle;' /> Amazon S3"]

Test It¶

# Check health
curl http://localhost:8000/health

# List all available models
curl http://localhost:8000/search_models

# Search models by capability (e.g. streaming-capable chat models only)
curl "http://localhost:8000/search_models?route=/v1/chat/completions&streaming=true"

# Chat completion
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Interactive API docs: Open http://localhost:8000/docs for Swagger UI with all available endpoints.

Point an application at it: set the base_url (Python) / baseURL (Node.js) option to http://localhost:8000/v1 (OpenAI SDK) or http://localhost:8000/anthropic (Anthropic SDK). Often that is the whole change: each model is published under the name its provider uses, so a model field already reading claude-sonnet-5 or gpt-oss-120b resolves as it stands. Change it where the name differs — one your application hard-codes for a model this deployment does not serve, such as gpt-4o or dall-e-3, returns 404 here until you point it at a model from the catalog above or map it with MODEL_ALIASES, while every model your regions serve is one name away. No API key is required by default — pass any non-empty string if your client insists on one. The API Overview has SDK snippets for Python, Node.js, and more.

Technical Notes¶

Building from source: See the Dockerfile if you prefer to build the image yourself.

Container runtime: Both community and Marketplace images use Granian, a high-performance Python ASGI server. Granian environment variables (e.g., GRANIAN_PORT, GRANIAN_WORKERS) are supported.

Configuration: See Configuration Reference for all environment variables.

Next Steps¶

stdapi.ai works with any OpenAI or Anthropic-compatible tool. Here are popular integrations to try locally: