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

# Deployment Options

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

ZeptoClaw supports four primary deployment modes, each optimized for different use cases ranging from local development to production multi-tenant hosting. This page provides an overview of each mode with configuration examples and technical implementation details.

Related pages: [Docker Deployment](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Docker Deployment) (12.2), [Container Gateway Mode](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Container Gateway Mode) (12.3), [Panel Deployment](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Panel Deployment) (12.4), [Multi-tenant Configuration](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Multi-tenant Configuration) (12.5), [Tunnel Integration](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Tunnel Integration) (12.6)

## Deployment Modes Overview

ZeptoClaw is designed as a single Rust binary that can operate in multiple capacities based on CLI flags and configuration. It is built for efficiency, requiring only ~6MB of RAM at idle [deploy/README.md64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L64-L64)

Sources: [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md195-205](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L195-L205) [deploy/README.md64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L64-L64)

## Mode 1: Native Binary Deployment

Native binary deployment executes the `zeptoclaw` binary directly on the host system. This provides the fastest startup and lowest memory footprint.

### Binary Architecture and Entry Points

The binary routes commands through CLI entry points. The `cmd_daemon` function provides a supervised wrapper for long-running services like the gateway, implementing automatic restarts with exponential backoff [src/cli/daemon.rs67-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L67-L151)

```

```

**Native Binary Command Routing**

Sources: [src/cli/daemon.rs67-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L67-L151) [src/cli/doctor.rs33-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L49)

### Installation Methods

Sources: [deploy/setup.sh5-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/setup.sh#L5-L22) [Makefile19-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Makefile#L19-L22)

## Mode 2: Docker Deployment

Docker deployment provides portability and reproducible environments. ZeptoClaw provides official images via `ghcr.io/qhkm/zeptoclaw` [.github/workflows/docker.yml28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L28-L28)

### Dockerfile Architecture

The `Dockerfile` uses a multi-stage build strategy. Stage 1 (`builder`) uses `rust:1.93-slim-trixie` to compile the release binary [Dockerfile10-42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L10-L42) Stage 2 (`runtime`) uses `debian:trixie-slim` to provide a minimal environment containing only the binary, `ca-certificates`, `git`, `gosu`, and `wget` [Dockerfile46-58](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L46-L58)

```

```

**Docker Multi-Stage Build Flow**

Sources: [Dockerfile1-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L1-L78) [.github/workflows/docker.yml1-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L1-L41)

## Mode 3: Containerized Gateway Mode

In this mode, the gateway service acts as an orchestrator. Instead of running the `AgentLoop` in the same process, it can spawn isolated container instances for each request to provide security boundaries against prompt injection.

### Implementation and Health

The system uses `zeptoclaw config check` as a health check mechanism in containerized environments [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md74](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L74-L74) The `docker-entrypoint.sh` handles permissions and initialization before starting the process [Dockerfile74](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L74-L74)

Sources: [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md73-75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L73-L75) [Dockerfile74](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L74-L74)

## Mode 4: Panel Deployment

The Panel deployment enables a web-based management interface. This includes a dashboard for monitoring system health and usage metrics.

### Key Components

- Health Monitoring : The run_diagnostics function in doctor.rs checks configuration, workspace writability, binary dependencies (like sh and git ), and provider connectivity src/cli/doctor.rs 33-49
- Daemon Supervision : The cmd_daemon tracks component status, restart counts, and errors in a DaemonState struct persisted to daemon_state.json src/cli/daemon.rs 21-40

Sources: [src/cli/doctor.rs1-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L1-L140) [src/cli/daemon.rs1-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L1-L151)

## Persistent Data Requirements

To ensure continuity across restarts, the following data must be persisted. In Docker, this is handled by mounting the `/data` volume [Dockerfile71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L71-L71)

Sources: [Dockerfile71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L71-L71) [src/cli/doctor.rs225-226](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L225-L226) [src/cli/daemon.rs21-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L21-L22)

## Health Monitoring and Diagnostics

ZeptoClaw includes a `doctor` utility to verify deployment health.

1. System Diagnostics : run_diagnostics checks for required binaries like git (needed for skill installation) and sh (needed for shell tools) src/cli/doctor.rs 101-106
2. Workspace Integrity : The system probes the workspace directory to ensure it is writable by creating a .zeptoclaw_doctor_probe file src/cli/doctor.rs 81-84
3. Daemon Health : The cmd_daemon monitors the gateway component and updates its ComponentState with running status and restart_count src/cli/daemon.rs 88-99

Sources: [src/cli/doctor.rs33-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L140) [src/cli/daemon.rs88-133](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L88-L133) [deploy/README.md159-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L159-L166)
