---
title: Local Development - Run stdapi.ai with Docker
description: Run stdapi.ai locally with Docker or Podman for development, testing,
  and evaluation. Free hardened image with full API compatibility for Amazon Bedrock
  models.
keywords: Docker OpenAI gateway, local AI development, Podman AI gateway, free OpenAI
  alternative, local AWS Bedrock, Docker AI API, community AI gateway, AGPL AI gateway
---

# :material-docker: Local Development with Docker/Podman

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

??? info "Before you start"
    To run stdapi.ai locally you need:

    1. **[Docker](https://docs.docker.com/get-started/get-docker/) or [Podman](https://podman.io/docs/installation)** installed
    2. An **AWS account** — [create one free](https://aws.amazon.com/free/)
    3. **AWS credentials** configured locally — via `aws configure` or `aws sso login` ([AWS CLI setup guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html))

---

## :material-docker: Run It

**With AWS credentials (after `aws sso login`):**

```bash
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.

!!! info "Why `--user`"
    The image runs as the unprivileged user `nonroot` (uid/gid **65532**). Your
    `~/.aws` files are owned by your own account and are usually readable by it
    alone, so the container is told to run as you instead. Skip both flags if you
    pass credentials as environment variables, as below — nothing else in the
    image needs your identity.

    **Never run this command with `sudo`.** `$(id -u):$(id -g)` is evaluated on
    the host: under `sudo` it resolves to `0:0`, and the container silently runs
    as root instead of `nonroot`. If your host has no `docker` group and you
    would otherwise need `sudo`, use the environment-variable form below instead.

**With environment variables instead:**

```bash
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
```

??? info "Podman on Fedora/RHEL with SELinux"

    Add the `:z` SELinux label and `--userns=keep-id:uid=65532,gid=65532`:

    ```bash
    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
    ```

    The `:z` flag relabels files for container access. Use `:Z` if multiple containers share the volume. `--userns=keep-id:uid=65532,gid=65532` makes your host account appear inside the container as the user the image runs as, so your `~/.aws` files stay readable; use it instead of the `--user` and `HOME` flags above, not alongside them.

    See also [Troubleshooting → Podman volume mount fails on Fedora/RHEL with SELinux](operations_troubleshooting.md#local-docker-podman) if you hit this after the fact.

```mermaid
%%{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"]
```

---

## :material-check-circle: Test It

```bash
# 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](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`](operations_configuration_models.md#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](api_overview.md) has SDK snippets for Python, Node.js, and more.

!!! tip "Try other models"
    `amazon.nova-micro-v1:0` is a fast, low-cost model — great for confirming the pipeline works. Once you see a response, switch the `model` field to `anthropic.claude-fable-5`, `anthropic.claude-sonnet-5`, or any other Bedrock model available in your configured regions.

    Use `GET /search_models` (shown above) to discover what's available and filter by capability, or `GET /v1/models` for strict OpenAI SDK compatibility — see the [Search Models API](api_search_models.md) reference.

!!! tip "Optional: expose the API as MCP tools"
    The [MCP server](features.md#mcp-model-context-protocol) is off by default. Add `-e ENABLE_MCP_STREAMABLE_HTTP=true` to the `docker run` command and every endpoint becomes a named MCP tool at `http://localhost:8000/mcp`, callable directly by Claude Code or any MCP client.

    Every exposed tool adds its schema to each MCP client's context window, so expose only the tools you actually use — for example `-e MCP_INCLUDE_TOOLS=openai_chat_completion,openai_embedding,search_models`. See the [MCP configuration reference](operations_configuration_server.md#summary-mcp).

---

## :material-information: Technical Notes

**Building from source:** The repository's [Dockerfile](https://github.com/stdapi-ai/stdapi.ai/blob/main/Dockerfile) builds the published image. To build it yourself, run `docker build -t stdapi.ai .` from the repository root. The build compiles FFmpeg from source.

**Container runtime:** The image uses [Granian](https://github.com/emmett-framework/granian), a high-performance Python ASGI server. Granian environment variables (e.g., `GRANIAN_PORT`, `GRANIAN_WORKERS`) are supported.

**Configuration:** See [Configuration Reference](operations_configuration.md) for all environment variables.

!!! tip "Ready for Production?"
    When you're ready to deploy to AWS with HTTPS and auto-scaling, the [production deployment guide](operations_getting_started.md) gets you running with two Terraform commands, using the hardened image `ghcr.io/stdapi-ai/stdapi.ai`.

---

## :material-arrow-right: Next Steps

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

<div class="grid cards" markdown>

- :material-chat: [**Open WebUI**](use_cases_openwebui.md) — Private ChatGPT-like interface with RAG, multi-modal support, and document upload
- :material-robot: [**n8n Workflows**](use_cases_n8n.md) — AI-powered automation with 400+ integrations
- :material-code-braces: [**AI Coding Assistants**](use_cases_coding_assistants.md) — Claude Code, Cline, OpenCode, Zed with Amazon Bedrock models
- :material-book-open-variant: [**API Overview**](api_overview.md) — All endpoints, parameters, and usage examples
- :material-rocket-launch: [**Getting Started**](operations_getting_started.md) — Deploy the production stack on AWS with Terraform
- :material-wrench: [**Troubleshooting**](operations_troubleshooting.md) — Podman/SELinux, auth, model-not-found, and other common errors

</div>
