<!-- source: https://deepwiki.com/qhkm/zeptoclaw/11.1-gateway-service -->

# Gateway Service

- src/channels/manager.rs
- src/channels/types.rs
- src/cli/gateway.rs
- src/cron/mod.rs
- src/gateway/startup_guard.rs
- src/heartbeat/mod.rs
- src/heartbeat/service.rs
- src/plugins/loader.rs
- src/plugins/registry.rs
- src/plugins/types.rs
- src/plugins/watcher.rs

The Gateway Service is the long-running orchestrator that manages multi-channel bot operations. It initializes and supervises all ZeptoClaw subsystems including channels, agents, health monitoring, background services, and plugin management. This page documents its architecture, startup sequence, execution modes, and lifecycle management.

For information about individual channel implementations, see [Communication Channels](/qhkm/zeptoclaw/7-communication-channels). For details on the underlying message routing system, see [Message Bus and Routing](/qhkm/zeptoclaw/3.3-message-bus-and-routing). For supervised daemon mode with automatic restart, see [Daemon Supervision](/qhkm/zeptoclaw/11.5-daemon-supervision).

## Overview

The Gateway Service (`cmd_gateway`) serves as ZeptoClaw's primary server mode, providing:

- Multi-channel coordination via ChannelManager src/channels/manager.rs 39-85
- Message routing through MessageBus pub/sub hub src/cli/gateway.rs 105
- Agent execution in containerized or in-process modes src/cli/gateway.rs 161-268
- Health monitoring with liveness/readiness endpoints src/cli/gateway.rs 112-155
- Background services including cron scheduling and heartbeat monitoring src/cli/gateway.rs 304-368
- Plugin System Integration for external tool extension src/plugins/registry.rs 1-20
- Configuration hot-reload with transactional rollback src/cli/gateway.rs 417-510
- Graceful shutdown with component cleanup coordination src/cli/gateway.rs 512-560

The gateway runs indefinitely until terminated via `Ctrl+C`, making it suitable for production deployments.

**Sources:** [src/cli/gateway.rs1-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L1-L31) [src/channels/manager.rs1-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L1-L15) [src/plugins/registry.rs1-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/registry.rs#L1-L20)

## Architecture and Key Components

The following diagram maps the Gateway Service's code entities to their architectural roles:

**Gateway Architecture Map**

```

```

**Key Code Entities:**

**Sources:** [src/cli/gateway.rs27-155](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L27-L155) [src/channels/manager.rs86-138](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L86-L138) [src/heartbeat/service.rs67-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L67-L98) [src/plugins/registry.rs60-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/registry.rs#L60-L66)

## Startup Sequence

The gateway initializes components in a specific order to ensure dependencies are satisfied:

**Gateway Startup Flow**

```

```

**Initialization Steps:**

1. Configuration Load src/cli/gateway.rs 34 Reads configuration and applies environment overrides.
2. Startup Guard Check src/cli/gateway.rs 38-61 Detects consecutive crashes within a time window via CrashState src/gateway/startup_guard.rs 16-24 Enters degraded mode if threshold exceeded, disabling shell , write_file , and edit_file src/cli/gateway.rs 49-53
3. Infrastructure Setup src/cli/gateway.rs 105-155 Creates MessageBus for pub/sub routing. Initializes UsageMetrics and HealthRegistry . Starts health servers (Legacy on :9090 and Named-check on config port).
4. Plugin Discovery src/plugins/loader.rs 43-102 Scans plugin_dirs for plugin.json manifests. Validates manifests for safety (e.g., rejecting dangerous shell operators) src/plugins/loader.rs 156-181 Registers tools in the PluginRegistry ensuring name uniqueness src/plugins/registry.rs 92-127
5. Agent Mode Resolution src/cli/gateway.rs 161-268 Containerized : Resolves Docker/Apple backend and creates ContainerAgentProxy . In-Process : Creates AgentLoop directly via create_agent .
6. Channel Registration src/cli/gateway.rs 287-302 Registers channels with ChannelManager . Starts all channels concurrently.
7. Background Services src/cli/gateway.rs 304-368 Starts HeartbeatService src/heartbeat/service.rs 102 and CronService if enabled.

**Sources:** [src/cli/gateway.rs27-423](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L27-L423) [src/heartbeat/service.rs102-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L102-L159) [src/plugins/loader.rs43-181](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/loader.rs#L43-L181) [src/gateway/startup_guard.rs16-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/startup_guard.rs#L16-L24)

## Execution Modes

### In-Process Mode (Default)

In this mode, the agent runs within the same process as the Gateway Service.

**Characteristics:**

- Direct memory sharing via Arc<MessageBus> .
- Lowest latency (no IPC overhead).
- Suitable for trusted environments where isolation is not a priority.

**Sources:** [src/cli/gateway.rs261-268](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L261-L268) [src/cli/gateway.rs370-392](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L370-L392)

### Containerized Mode

The agent runs in an isolated container (Docker or Apple Virtualization).

**Characteristics:**

- IPC via stdin/stdout JSON protocol.
- Per-request container spawn or persistent proxy.
- Backend resolved via resolve_backend src/cli/gateway.rs 166

**Sources:** [src/cli/gateway.rs161-259](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L161-L259) [src/gateway/](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/)

## Channel Management and Supervision

The `ChannelManager` orchestrates channel lifecycles with automatic restart on failure:

**Channel Lifecycle State Machine**

```

```

**Supervision Mechanism:**

- Polling Interval : 15 seconds src/channels/manager.rs 26
- Cooldown : 60 seconds between restart attempts src/channels/manager.rs 28
- Max Restarts : 5 per channel src/channels/manager.rs 30

**Sources:** [src/channels/manager.rs25-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L25-L37) [src/channels/manager.rs159-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L159-L206)

## Background Services

### Heartbeat Service

Periodically enqueues `HEARTBEAT_PROMPT` to the message bus to wake up the agent [src/heartbeat/service.rs15-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L15-L18)

- Actionable Check : is_empty() parses HEARTBEAT.md for non-comment, non-empty lines src/heartbeat/service.rs 188-200
- Failure Tracking : Tracks consecutive failed ticks to report service degradation src/heartbeat/service.rs 75-77

### Cron Service

Handles persistent scheduling of agent turns [src/cron/mod.rs1-3](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L1-L3)

- Schedules : Supports At (one-time), Every (interval), and Cron (expression) src/cron/mod.rs 19-23
- Error Backoff : Implements a 5-tier backoff schedule for failing jobs src/cron/mod.rs 87-93

**Sources:** [src/heartbeat/service.rs15-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L15-L200) [src/cron/mod.rs17-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L17-L93)

## Graceful Shutdown

The gateway handles `Ctrl+C` by coordinating the stop sequence across all subsystems:

1. Readiness : Sets metrics.ready = false src/cli/gateway.rs 516
2. Usage Flush : Signals the final periodic usage flush src/cli/gateway.rs 519-520
3. Heartbeat : Stops the HeartbeatService src/cli/gateway.rs 522-524
4. Agent/Proxy : Calls stop() on the agent or container proxy src/cli/gateway.rs 527-533
5. Channels : Calls channel_manager.stop_all() src/cli/gateway.rs 536-539
6. Cleanup : Awaits tasks with a timeout before forcing exit src/cli/gateway.rs 546-551

**Sources:** [src/cli/gateway.rs512-560](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L512-L560)
