Environment:Guardrails ai Guardrails Docker Server Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Deployment |
| Last Updated | 2026-02-14 12:00 GMT |
Overview
Docker containerized environment for deploying Guardrails AI as an API server using Flask/Gunicorn or FastAPI/Uvicorn.
Description
This environment defines the Docker-based deployment context for running Guardrails AI as a production API server. The server CI scripts support two WSGI/ASGI backends: Flask with Gunicorn and FastAPI with Uvicorn. The Docker build process installs the `guardrails-ai[api]` extra, configures guard definitions, and exposes the validation API on a configurable port. The environment also requires a remote Guardrails API base URL and API key for client applications connecting to the server.
Usage
Use this environment for production Server_Deployment workflows. Required when running Guardrails as a standalone API service behind Docker, Kubernetes, or any container orchestrator. Client applications use `Guard.load()` to connect to the remote server.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (container host) | Docker Desktop for macOS/Windows development |
| Docker | Docker Engine 20.10+ | For multi-stage builds |
| Network | Port 8000 (default) | Configurable via GUARDRAILS_BASE_URL |
| Memory | >= 512MB container RAM | Depends on validators loaded |
Dependencies
System Packages (inside container)
- Python >= 3.10
- `guardrails-ai[api]` (installs `guardrails-api` and `boto3`)
Server Backends
- Flask mode: `gunicorn` (WSGI server)
- FastAPI mode: `uvicorn` (ASGI server)
CI Test Dependencies
- `pytest`
- `pytest-asyncio`
- `openai`
Credentials
The following environment variables must be set:
- `GUARDRAILS_BASE_URL`: Base URL of the Guardrails API server (default: `http://localhost:8000`). Used by client applications.
- `GUARDRAILS_API_KEY`: API key for authenticating with the Guardrails server. Used by client applications.
- `OPENAI_API_KEY`: OpenAI API key, forwarded to the server via `x-openai-api-key` header during validation requests.
Quick Install
# Install with API server support
pip install "guardrails-ai[api]"
# Generate server configuration
guardrails create --name my-config
# Start development server
guardrails start
Code Evidence
Server base URL configuration from `guardrails/api_client.py:31-35`:
self.base_url = (
base_url
if base_url is not None
else os.environ.get("GUARDRAILS_BASE_URL", "http://localhost:8000")
)
API key configuration from `guardrails/api_client.py:37-38`:
self.api_key = (
api_key if api_key is not None else os.environ.get("GUARDRAILS_API_KEY", "")
)
Flask entrypoint from `server_ci/flask-entry.sh`:
gunicorn --bind 0.0.0.0:8000 --timeout 90 --threads 10 "guardrails_api.app:create_app()"
FastAPI entrypoint from `server_ci/fastapi-entry.sh`:
uvicorn "guardrails_api.app:create_app" --host 0.0.0.0 --port 8000 --factory
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Connection refused` on port 8000 | Server not running or wrong port | Verify `GUARDRAILS_BASE_URL` and that the container is running |
| `ModuleNotFoundError: guardrails_api` | API extra not installed | `pip install "guardrails-ai[api]"` |
| `status_code: 401` | Missing or invalid API key | Set `GUARDRAILS_API_KEY` environment variable |
| `The response from the server was empty!` | Server returned no data | Check server logs; may indicate guard config issue |
Compatibility Notes
- Flask vs FastAPI: Both backends are supported. Flask uses Gunicorn with 10 threads and 90s timeout. FastAPI uses Uvicorn with factory pattern.
- Timeout: The default client timeout is 300 seconds (5 minutes) as set in `api_client.py:40`.
- History: Remote guard history can be disabled via `GUARD_HISTORY_ENABLED=false` to reduce API calls.
- Streaming: Remote streaming validation uses raw HTTP streaming with `requests.Session` rather than the generated API client.