Docker

Docker is the recommended way to deploy Sesame long-term.

Container Images

Pre-built images are available from:

Registry	Image
GitHub Container Registry (recommended)	`ghcr.io/jakejarvis/sesame`
Docker Hub	`docker.io/jakejarvis/sesame`

Sandbox Image

When using the Docker sandbox provider, a separate image is used for running agent tasks:

Registry	Image
GitHub Container Registry	`ghcr.io/jakejarvis/sesame-sandbox`
Docker Hub	`docker.io/jakejarvis/sesame-sandbox`

This image comes pre-loaded with mise, common runtimes (Node.js, Python, Go, Rust, Ruby, Bun), and all agent CLIs. See Docker Sandbox for details.

Available Tags

Tag	Description
`latest`	Latest stable release from `main` branch
`v1.0.0`	Specific version
`v1.0`	Latest patch of minor version
`v1`	Latest minor/patch of major version
`sha-abc1234`	Specific commit

Docker Compose (Recommended)

1. Create Configuration

# Create a directory for your deployment
mkdir sesame && cd sesame

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/jakejarvis/sesame/main/docker-compose.yml

# Create .env file
cat > .env << 'EOF'
BETTER_AUTH_SECRET=your-secret-here
BASE_URL=http://localhost:13531
ENCRYPTION_KEY=your-encryption-key-here
EOF

Generate secrets:

# Generate and update .env with real values
openssl rand -base64 32  # Use for BETTER_AUTH_SECRET
openssl rand -hex 32     # Use for ENCRYPTION_KEY

2. Start the Container

docker compose up -d

View logs:

docker compose logs -f

3. Access the App

Navigate to http://localhost:13531. The first user to sign up becomes admin.

Configuration Options

Environment Variables

Required:

Variable	Description
`BETTER_AUTH_SECRET`	Auth encryption secret (min 32 chars)
`BASE_URL`	Public URL of your deployment
`ENCRYPTION_KEY`	Data encryption key (64 hex chars)

Optional:

Variable	Description
`AI_API_KEY`	API key for utility AI tasks
`AI_BASE_URL`	OpenAI-compatible API URL
`AI_MODEL`	Model for utility tasks (default: gpt-4o-mini)
`OIDC_ENABLED`	Enable SSO (see Authentication)

Config File

Mount a config file for settings editable via the admin UI:

docker-compose.yml

services:
  sesame:
    volumes:
      - ./config.json:/app/config.json
      - sesame-data:/app/data
      - sesame-sandboxes:/app/sandboxes

config.json

{
  "ai": {
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini"
  }
}

Environment variables take precedence over config.json and lock settings in the admin UI.

Building from Source

To build the image locally instead of using pre-built images:

# Clone the repository
git clone https://github.com/jakejarvis/sesame.git
cd sesame

# Build the image
docker build -t sesame .

# Run with docker compose (update image in docker-compose.yml)
docker compose up -d

Or use docker-compose to build:

docker-compose.yml

services:
  sesame:
    build:
      context: .
      dockerfile: Dockerfile
    # Remove or comment out the 'image:' line

Docker Sandbox Provider

To run agent tasks in isolated Docker containers (instead of directly on the host), you need to give Sesame access to a Docker daemon.

By default, agent tasks use the sesame-sandbox image, which has mise, common runtimes, and all agent CLIs pre-installed for fast task startup.

Quick Setup

Add the Docker socket mount and enable the provider:

docker-compose.yml

services:
  sesame:
    environment:
      - SANDBOX_PROVIDER=docker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      # Use bind mount so host Docker can access sandbox files
      - ./sandboxes:/app/sandboxes

Mounting the Docker socket grants significant privileges. Consider using docker-socket-proxy to limit API access. See the Docker Sandbox docs for details.

Using docker-socket-proxy

For better security, use the included socket proxy configuration:

docker compose -f docker-compose.yml -f docker-compose.socket-proxy.yml up -d

This runs a proxy that only exposes the Docker API endpoints Sesame needs (containers, exec, images, version).

Why Not Docker-in-Docker?

Running Docker inside the Sesame container (DinD) is possible but not recommended:

Requires --privileged mode
Adds latency and complexity
Image cache doesn't persist
Known storage driver issues

Using the host's Docker daemon avoids these problems while still providing container isolation for agent tasks.

services:
  sesame:
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 1G

Health Checks

The container includes a health check by default. To customize:

docker-compose.yml

services:
  sesame:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:13531/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Updating

# Pull the latest image
docker compose pull

# Restart with the new image
docker compose up -d

Database migrations run automatically on container startup.

Troubleshooting

Container Won't Start

Check logs for errors:

docker compose logs sesame

Common issues:

Missing required environment variables (BETTER_AUTH_SECRET, ENCRYPTION_KEY)
Port 13531 already in use
Insufficient permissions on mounted volumes

Database Issues

Reset the database (caution: deletes all data):

docker compose down
docker volume rm sesame_sesame-data
docker compose up -d

View Container Shell

docker compose exec sesame sh

Container Images

Sandbox Image

Available Tags

Docker Compose (Recommended)

1. Create Configuration

2. Start the Container

3. Access the App

Configuration Options

Environment Variables

Config File

Building from Source

Docker Sandbox Provider

Quick Setup

Using docker-socket-proxy

Why Not Docker-in-Docker?

Additional Configuration

Reverse Proxy

Resource Limits

Health Checks

Updating

Troubleshooting

Container Won't Start

Database Issues

View Container Shell

On this page