Skip to main content
NOMOS provides multiple deployment options to suit different environments and requirements.

​
CLI Deployment

​
Quick Deployment with CLI

The simplest way to deploy your agent is using the NOMOS CLI: 
# Deploy with FastAPI server
nomos serve --config config.agent.yaml

CLI Usage Guide

See complete deployment options in the CLI documentation

​
Docker Base Image

NOMOS provides a base Docker image that you can use to quickly containerize your agents. The base image is available on Docker Hub as dowhiledev/nomos-base.
1

Create a Dockerfile using the base image

# If using the base image
FROM ghcr.io/dowhiledev/nomos:latest
# Copy your config file
COPY config.agent.yaml /app/config.agent.yaml
# Copy your tools
COPY tools.py /app/src/tools/
CMD ["nomos", "serve", "--config", "config.agent.yaml", "--workers", "4"]
2

Or Build from scratch

# If building from scratch
FROM python:3.11-slim
WORKDIR /app
# Install dependencies
RUN pip install nomos[cli,openai]
# Copy files
COPY . /app/
CMD ["nomos", "serve", "--config", "config.agent.yaml"]
3

Build and run your container

docker build -t your-nomos-agent .
docker run -e OPENAI_API_KEY=your-api-key-here -p 8000:8000 your-nomos-agent

​
Environment Variables

Essential environment variables for deployment:
VariableDescriptionRequired
OPENAI_API_KEYOpenAI API keyIf using OpenAI
ANTHROPIC_API_KEYAnthropic API keyIf using Anthropic
MISTRAL_API_KEYMistral API keyIf using Mistral
GOOGLE_API_KEYGoogle API keyIf using Gemini
HUGGINGFACE_API_TOKENHuggingFace tokenIf using HuggingFace
JWT_SECRET_KEYJWT secret keyIf using JWT auth
CSRF_SECRET_KEYCSRF secret keyIf using CSRF protection
API_KEY_VALIDATION_URLAPI key validation endpoint URLIf using API key auth
SESSION_STORESession store typeOptional
DATABASE_URLDatabase connection URLIf using production session store
REDIS_URLRedis connection URLIf using production session store

​
Security Configuration

NOMOS now includes comprehensive security features that can be configured for production deployments:

​
Authentication

server:
  security:
    enable_auth: true
    auth_type: jwt
    jwt_secret_key: "$JWT_SECRET_KEY"

​
Rate Limiting & CSRF Protection

server:
  security:
    # Rate limiting
    enable_rate_limiting: true
    rate_limit: "100/minute"

    # CSRF protection
    enable_csrf_protection: true
    csrf_secret_key: "$CSRF_SECRET_KEY"

    # CORS configuration
    allowed_origins:
      - "https://your-frontend.com"
      - "https://your-admin.com"

Security Documentation

Complete security configuration guide

​
Production Considerations

Security

Enable authentication, rate limiting, and CSRF protection

Scaling

Configure multiple workers for high traffic

Monitoring

Enable logging and monitoring for production

Health Checks

Built-in health check endpoints at /health

​
Cloud Deployment

​
Docker Compose

For orchestrated deployments: 
services:
  your-nomos-agent:
    build: .
    ports:
      - "8000:8000"
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      # Security configuration
      JWT_SECRET_KEY: ${JWT_SECRET_KEY}
      CSRF_SECRET_KEY: ${CSRF_SECRET_KEY}
      # Session store configuration
      SESSION_STORE: production
      DATABASE_URL: postgresql+asyncpg://nomos:nomos@postgres/nomos
      REDIS_URL: redis://redis:6379/0
      KAFKA_BROKERS: kafka:9092
      SESSION_EVENTS: "true"
    depends_on:
      - postgres
      - redis
      - kafka
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
  postgres:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: nomos
      POSTGRES_USER: nomos
      POSTGRES_PASSWORD: nomos
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U nomos"]
      interval: 10s
      timeout: 5s
      retries: 5
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
  kafka:
    image: bitnami/kafka:latest
    environment:
      # KRaft mode configuration (without Zookeeper)
      KAFKA_CFG_NODE_ID: 0
      KAFKA_CFG_PROCESS_ROLES: controller,broker
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: 0@kafka:9093
      KAFKA_CFG_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
      KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      # Allow auto-creation of topics
      KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "true"
    ports:
      - "9092:9092"
    volumes:
      - kafka_data:/bitnami/kafka
volumes:
  postgres_data:
  redis_data:
  kafka_data:

​
Kubernetes

Basic Kubernetes deployment: 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nomos-agent
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nomos-agent
  template:
    metadata:
      labels:
        app: nomos-agent
    spec:
      containers:
      - name: nomos-agent
        image: your-nomos-agent:latest
        ports:
        - containerPort: 8000
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: api-keys
              key: openai-key
        - name: JWT_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: security-keys
              key: jwt-secret
        - name: CSRF_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: security-keys
              key: csrf-secret
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: nomos-agent-service
spec:
  selector:
    app: nomos-agent
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8000
  type: LoadBalancer
Remember to properly manage secrets and API keys in production environments. Use Kubernetes secrets or your cloud provider’s secret management service.

​
Secure Docker Configuration

For production deployments, create a secure Docker configuration: 
FROM python:3.11-slim

# Create non-root user
RUN useradd -m -u 1000 nomos && \
    mkdir -p /app && \
    chown -R nomos:nomos /app

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY --chown=nomos:nomos . .

# Switch to non-root user
USER nomos

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

# Run the application
CMD ["nomos", "serve", "--config", "config.agent.yaml", "--workers", "4"]