<!-- source: https://deepwiki.com/qhkm/zeptoclaw/12-deployment -->

# Deployment

- .github/workflows/docker.yml
- Dockerfile
- deploy/README.md
- landing/zeptoclaw/docs/src/content/docs/guides/deployment.md
- src/cli/daemon.rs
- src/cli/doctor.rs

## Purpose and Scope

This document provides an overview of ZeptoClaw's deployment strategies and architectural configurations. It covers the primary deployment modes (native CLI, gateway server, containerized gateway, and panel UI), explains how system components interact in production environments, and outlines configuration requirements for different deployment scenarios.

For detailed coverage of specific topics:

- Docker container configuration and multi-stage builds: see Docker Deployment
- Per-request container isolation with ContainerAgentProxy : see Container Gateway Mode
- Web UI deployment with REST API and WebSocket events: see Panel Deployment
- Multi-user isolation and workspace strategies: see Multi-tenant Configuration
- Public exposure via tunnels: see Tunnel Integration

## Deployment Modes

ZeptoClaw supports several distinct deployment modes, each optimized for different use cases:

Sources: [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md47-56](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L47-L56) [src/cli/daemon.rs67-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L67-L151) [deploy/README.md64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L64-L64)

## System Architecture: Deployment View

The following diagram bridges the high-level deployment modes to specific code entities and runtime environments:

```

```

**Key Observations:**

- Daemon Mode wraps the cmd_gateway execution, maintaining a DaemonState to track restarts and errors src/cli/daemon.rs 88-132
- Containerized Gateway utilizes the Dockerfile to provide a consistent environment, leveraging a multi-stage build for minimal runtime size Dockerfile 8-46
- Gateway Mode acts as the primary orchestration layer for ChannelManager and MessageBus deploy/README.md 156-161

Sources: [src/cli/daemon.rs88-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L88-L132) [Dockerfile8-46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L8-L46) [deploy/README.md156-161](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L156-L161)

## Deployment Flow and Lifecycle

The following diagram illustrates the startup sequence and runtime lifecycle for the Gateway and Panel modes:

```

```

**Self-Diagnostics:** Before and during deployment, the `doctor` module performs extensive checks, including workspace writability and binary availability (e.g., `git`, `sh`) [src/cli/doctor.rs33-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L49) It probes for binaries using `Command::new(name).arg("--version")` to avoid reliance on `which` in minimal containers [src/cli/doctor.rs115-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L115-L120)

Sources: [src/cli/daemon.rs102-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L102-L132) [src/cli/doctor.rs33-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L49) [src/cli/doctor.rs115-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L115-L120) [src/cli/daemon.rs17-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L17-L19)

## Installation and Platform Options

ZeptoClaw provides several installation paths and platform-specific templates:

### Containerized Deployment

- Docker Hub / GHCR: Pre-built images are automatically built and pushed to ghcr.io/qhkm/zeptoclaw on tag events github/workflows/docker.yml 28-39
- Multi-stage Build: The Dockerfile reduces the final image size by separating the build environment ( rust:1.93-slim-trixie ) from the runtime ( debian:trixie-slim ) Dockerfile 10-46
- Persistence: Mount /data to persist longterm.json memory and session history Dockerfile 71 landing/zeptoclaw/docs/src/content/docs/guides/deployment.md 181-193

### Cloud Platforms

- Fly.io: Deploy via fly.toml with internal_port = 8080 for the gateway landing/zeptoclaw/docs/src/content/docs/guides/deployment.md 87-104
- Railway / Render: Support for auto-deployment via GitHub triggers using railway.json or render.yaml deploy/README.md 117-142
- DigitalOcean: One-click deployment available via the DigitalOcean App Platform deploy/README.md 11

### Bare Metal / VPS

- Systemd: Recommended for Linux deployments to ensure the binary starts on boot and restarts on failure landing/zeptoclaw/docs/src/content/docs/guides/deployment.md 147-164
- Setup Script: An interactive wizard at zeptoclaw.com/setup.sh automates binary installation and initial LLM/Channel configuration deploy/README.md 20-28

Sources: [Dockerfile10-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L10-L71) [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md87-164](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L87-L164) [deploy/README.md11-142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L11-L142) [.github/workflows/docker.yml28-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L28-L39)

## Configuration Management

Deployment configuration is managed through a hierarchy:

1. Environment Overrides: Variables like ZEPTOCLAW_PROVIDERS_ANTHROPIC_API_KEY take precedence over file settings landing/zeptoclaw/docs/src/content/docs/guides/deployment.md 53-54
2. Health Monitoring: The zeptoclaw config check command or the /healthz endpoint on port 9090 can be used for container health checks landing/zeptoclaw/docs/src/content/docs/guides/deployment.md 74-75 deploy/README.md 161-166
3. Supervision: The daemon command implements an exponential backoff strategy via compute_backoff , starting at 1s ( INITIAL_BACKOFF_MS ) and capping at 5 minutes ( MAX_BACKOFF_MS ) src/cli/daemon.rs 14-19

Sources: [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md53-75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L53-L75) [deploy/README.md161-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L161-L166) [src/cli/daemon.rs14-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L14-L19)

## Next Steps

For detailed configuration of specific deployment modes, see:

- Deployment Options — Comparison matrix and mode-specific features
- Docker Deployment — Dockerfile breakdown, volume mounts, environment variables
- Container Gateway Mode — ContainerAgentProxy internals and IPC protocol
- Panel Deployment — REST API routes, WebSocket events, authentication
- Multi-tenant Configuration — Isolation strategies for shared infrastructure
- Tunnel Integration — Public exposure without port forwarding
