Containerization

This guide covers how to containerize Naylence components using Docker. We provide official Docker images for both TypeScript and Python SDKs, and show you how to create custom images when additional dependencies are needed.

Official Docker Images

Naylence provides ready-to-use Docker images on Docker Hub:

Language	Image	Base
TypeScript	`naylence/agent-sdk-node`	`node:24-slim`
Python	`naylence/agent-sdk-python`	`python:3.12-slim`

Both images:

Run as a non-root user (agent) for security
Include the SDK pre-installed
Are optimized for production use

Image Tags

Use semantic versioning to pin your images:


# TypeScript
naylence/agent-sdk-node:0.3.5
 
# Python
naylence/agent-sdk-python:0.3.12

Basic Docker Compose Setup

The most common pattern is a sentinel with one or more agents connected to it:

docker-compose.yml


x-images: &images
  base: &base-image naylence/agent-sdk-python:0.3.12
 
services:
  sentinel:
    image: *base-image
    ports:
      - "8000:8000"
    volumes:
      - .:/work:ro
    working_dir: /work
    command: ["python", "sentinel.py"]
    networks:
      - naylence-net
    stop_signal: SIGINT
    stop_grace_period: 1s
    healthcheck:
      test: ["CMD", "python", "-c", "import socket; s=socket.socket(); s.connect(('localhost', 8000)); s.close()"]
      interval: 0.5s
      timeout: 1s
      retries: 10
      start_period: 0.5s
      start_interval: 1s
 
  my-agent:
    image: *base-image
    volumes:
      - .:/work:ro
    working_dir: /work
    command: ["python", "my_agent.py"]
    depends_on:
      sentinel:
        condition: service_healthy
    networks:
      - naylence-net
    environment:
      - FAME_DIRECT_ADMISSION_URL=ws://sentinel:8000/fame/v1/attach/ws/downstream
 
networks:
  naylence-net:
    driver: bridge

Volume Mounting Strategies

TypeScript: Pre-compiled JavaScript

TypeScript examples mount the ./dist directory containing compiled JavaScript:


volumes:
  - ./dist:/app
  - /app/node_modules  # Preserve container's node_modules

The second volume (/app/node_modules) ensures the container’s pre-installed modules are used rather than any local node_modules.

Build workflow:


# Compile TypeScript to JavaScript
npm run build
 
# Start containers
docker compose up

Python: Source Files

Python examples mount source files directly:


volumes:
  - .:/work:ro  # Read-only mount
working_dir: /work

The :ro flag makes the mount read-only, which is a security best practice.

Run workflow:


# Start containers directly (no build step needed)
docker compose up

Environment Variables

Core Configuration

Variable	Description	Example
`FAME_DIRECT_ADMISSION_URL`	WebSocket URL to connect to sentinel	`ws://sentinel:8000/fame/v1/attach/ws/downstream`
`FAME_LOG_LEVEL`	Logging verbosity	`INFO`, `DEBUG`
`FAME_SHOW_ENVELOPES`	Show message envelopes in logs	`true`, `false`

Storage Configuration

For persistent storage, configure these variables:

Variable	Description	Example
`FAME_STORAGE_PROFILE`	Storage backend type	`memory`, `sqlite`, `encrypted-sqlite`
`FAME_STORAGE_MASTER_KEY`	Encryption key for encrypted-sqlite	32-byte hex string
`FAME_STORAGE_DB_DIRECTORY`	Directory for database files	`/work/data/agent`

Healthchecks

Proper healthchecks ensure dependent services start only after the sentinel is ready:


healthcheck:
  test: ["CMD", "python", "-c", "import socket; s=socket.socket(); s.connect(('localhost', 8000)); s.close()"]
  interval: 0.5s
  timeout: 1s
  retries: 10
  start_period: 0.5s
  start_interval: 1s

Then use depends_on with condition: service_healthy:


services:
  my-agent:
    depends_on:
      sentinel:
        condition: service_healthy

Custom Docker Images

When you need additional dependencies (like OpenAI, database drivers, etc.), create a custom Dockerfile that extends the base image.

Example: Adding OpenAI

Dockerfile


FROM naylence/agent-sdk-python:0.3.12
 
# Install additional packages
RUN pip install --no-cache-dir openai
 
WORKDIR /work

Then update your docker-compose.yml:

docker-compose.yml


services:
  my-agent:
    build: .
    volumes:
      - .:/work:ro
    working_dir: /work
    command: ["python", "my_agent.py"]
    # ... rest of configuration

Example: Adding Database Drivers

Dockerfile


FROM naylence/agent-sdk-python:0.3.12
 
RUN pip install --no-cache-dir pg8000
 
WORKDIR /work

Persistent Storage with Docker Volumes

For data that needs to survive container restarts, mount host directories:

docker-compose.yml


services:
  sentinel:
    image: naylence/agent-sdk-python:0.3.12
    volumes:
      - .:/work:ro
      - ./data/sentinel:/work/data/sentinel  # Persistent data (writable)
    environment:
      - FAME_STORAGE_PROFILE=sqlite
      - FAME_STORAGE_DB_DIRECTORY=/work/data/sentinel
    # ...
 
  my-agent:
    image: naylence/agent-sdk-python:0.3.12
    volumes:
      - .:/work:ro
      - ./data/agent:/work/data/agent  # Persistent data (writable)
    environment:
      - FAME_STORAGE_PROFILE=sqlite
      - FAME_STORAGE_DB_DIRECTORY=/work/data/agent
    # ...