Deploy: Docker - PraisonAI

Build and deploy agents as Docker containers using praisonai deploy run --type docker.

Quick Start - CLI

Install PraisonAI

pip install praisonai

Set API Key

export OPENAI_API_KEY="your-key"

Initialize Docker Config

praisonai deploy init --file agents.yaml --type docker

Deploy to Docker

praisonai deploy run --file agents.yaml --type docker

Expected Output:

🚀 Starting deployment...

📦 Building Docker image: praisonai-app:latest
  • Base image: python:3.11-slim
  • Exposing ports: [8005]

✅ Deployment successful!
🔗 URL: http://localhost:8005

Metadata:
  • type: docker
  • image: praisonai-app:latest
  • container_id: abc123def456

Verify

docker ps | grep praisonai
curl http://localhost:8005/health

Quick Start - SDK

Create Deploy Script

from praisonai.deploy import Deploy, DeployConfig, DeployType
from praisonai.deploy.models import DockerConfig

config = DeployConfig(
    type=DeployType.DOCKER,
    docker=DockerConfig(
        image_name="praisonai-app",
        tag="latest",
        base_image="python:3.11-slim",
        expose=[8005],
        push=False
    )
)

deploy = Deploy(config, "agents.yaml")
result = deploy.deploy()

print(f"Image: {result.metadata.get('image')}")
print(f"Container: {result.metadata.get('container_id')}")

Run

python deploy_docker.py

agents.yaml with Docker Config

framework: praisonai
topic: helpful assistant
roles:
  assistant:
    role: Assistant
    goal: Help users with their questions
    backstory: You are a helpful assistant
    tasks:
      help_task:
        description: Answer user questions
        expected_output: Helpful response

deploy:
  type: docker
  docker:
    image_name: "praisonai-app"
    tag: "latest"
    base_image: "python:3.11-slim"
    expose: [8005]
    push: false
    registry: null
  # Optional sibling block — configures the generated in-container server.
  api:
    host: 0.0.0.0
    port: 8005
    auth_enabled: false   # exposes /chat without a token

Docker Config Options

Field	Type	Default	Description
`image_name`	string	`praisonai-app`	Docker image name
`tag`	string	`latest`	Docker image tag
`base_image`	string	`python:3.11-slim`	Base Docker image
`expose`	list[int]	`[8005]`	Ports to expose
`registry`	string	`null`	Docker registry URL
`push`	bool	`false`	Push image to registry
`build_args`	dict	`null`	Docker build arguments

In-container API server (sibling `api:` block)

Docker deploys generate a Flask API server inside the container. Configure it with a sibling api: block under deploy:.

deploy:
  type: docker
  docker:
    image_name: praisonai-app
    expose: [8005]
  api:
    host: 0.0.0.0
    port: 8005
    auth_enabled: false   # /chat without a bearer token

Behavior	Effect
Omit the block	Auth on, CORS on, port 8005, bearer token required for `/chat`
`auth_enabled: false`	Injects `PRAISONAI_API_AUTH=disabled` into the container; `/chat` is reachable without a token
`auth_enabled: true` (or omitted)	No env override; the generated server enforces auth

The sibling api: block is type: docker-only. On type: cloud, the block is dropped (cloud providers shell out to external CLIs and do not generate the API server).

Push to Registry

deploy:
  type: docker
  docker:
    image_name: "praisonai-app"
    tag: "v1.0.0"
    registry: "your-registry.com/your-org"
    push: true

praisonai deploy run --file agents.yaml --type docker

Expected Output:

🚀 Starting deployment...

📦 Building Docker image: your-registry.com/your-org/praisonai-app:v1.0.0
📤 Pushing to registry: your-registry.com/your-org

✅ Deployment successful!

Metadata:
  • image: your-registry.com/your-org/praisonai-app:v1.0.0
  • pushed: true

Check Status

praisonai deploy status --file agents.yaml

Stop Container

praisonai deploy destroy --file agents.yaml

praisonai deploy destroy is cross-platform: on Windows it locates the API process with netstat -ano and terminates it with taskkill, falling back to lsof + SIGTERM on POSIX. This prevents orphaned background Flask API servers after teardown.

Expected Output:

⚠️  Warning: This will destroy the deployment!
File: agents.yaml
Service: praisonai-app

Type 'yes' to confirm destruction: yes

🗑️ Destroying deployment...

✅ Deployment destroyed successfully

Deleted resources:
  • container: praisonai-app-abc123
  • image: praisonai-app:latest (local)

Environment Variables

Variable	Required	Description
`OPENAI_API_KEY`	Yes*	OpenAI API key
`ANTHROPIC_API_KEY`	No	Anthropic API key
`GROQ_API_KEY`	No	Groq API key
`PRAISONAI_API_AUTH`	No	Set to `disabled` by the deploy layer when `api.auth_enabled: false`. Do not set manually.

*Required if using OpenAI models.

Troubleshooting

Issue	Fix
Docker not running	Start Docker daemon
Build failed	Check Dockerfile syntax, run `praisonai deploy doctor`
Push failed	Check registry credentials
Port in use	Change port in agents.yaml
Container exits	Check logs: `docker logs <container>`

Manual Docker Commands (Optional)

These commands are for manual validation only. Use praisonai deploy for deployment.

# Build manually
docker build -t praisonai-app:latest .

# Run manually
docker run -p 8005:8005 -e OPENAI_API_KEY=$OPENAI_API_KEY praisonai-app:latest

# Check logs
docker logs <container_id>

# Stop
docker stop <container_id>

Deploy CLI Overview - All deploy commands
API Deploy - Deploy as local API server
AWS Deploy - Deploy to AWS ECS/Fargate
GCP Deploy - Deploy to Google Cloud Run

​Quick Start - CLI

​Quick Start - SDK

​agents.yaml with Docker Config

​Docker Config Options

​In-container API server (sibling api: block)

​Push to Registry

​Check Status

​Stop Container

​Environment Variables

​Troubleshooting

​Related

Quick Start - CLI

Quick Start - SDK

agents.yaml with Docker Config

Docker Config Options

In-container API server (sibling `api:` block)

Push to Registry

Check Status

Stop Container

Environment Variables

Troubleshooting

Related