<!-- source: https://deepwiki.com/qhkm/zeptoclaw/4.3-gateway-commands -->

# Gateway Commands

- src/channels/manager.rs
- src/channels/types.rs
- src/cli/gateway.rs
- src/cron/mod.rs
- src/heartbeat/mod.rs
- src/heartbeat/service.rs
- src/plugins/watcher.rs
- src/tunnel/cloudflare.rs
- src/tunnel/ngrok.rs
- src/tunnel/tailscale.rs

## Purpose and Scope

Gateway commands start ZeptoClaw as a persistent service that processes messages from communication channels (Telegram, Slack, Discord, WhatsApp, Lark, Webhook). The gateway acts as a message router, consuming inbound messages from channels and publishing responses back to the originating channel. This mode is designed for multi-user deployments where ZeptoClaw runs continuously to handle chat-based interactions.

Gateway mode supports optional container isolation, where each request is processed in a separate Docker or Apple Container for security. It also integrates with tunnel providers (Cloudflare, ngrok, Tailscale) to expose webhook endpoints without manual port forwarding.

For single-shot agent interactions via CLI, see [Agent Commands](/qhkm/zeptoclaw/4.2-agent-commands). For configuration of gateway behavior, see [Configuration File Structure](/qhkm/zeptoclaw/5.1-configuration-file-structure).

## Basic Gateway Command

### Command Syntax

```

```

The `gateway` command (implemented in `cmd_gateway`) starts a persistent service that:

1. Loads Configuration : Reads config.json and applies overrides from flags like --containerized or --tunnel src/cli/gateway.rs 34-83
2. Initializes Components : Creates the MessageBus for async routing and UsageMetrics for tracking src/cli/gateway.rs 105-108
3. Starts Health Services : Launches a legacy health server and a named-check health registry on configured ports src/cli/gateway.rs 111-154
4. Registers Channels : Uses register_configured_channels to instantiate all enabled communication adapters src/cli/gateway.rs 206-210
5. Spawns Agent Loop : Depending on flags, starts either a local AgentLoop or a ContainerAgentProxy src/cli/gateway.rs 215-245

### Execution Flow

The following diagram illustrates the data flow from a CLI command to the running gateway service.

**Diagram: Gateway Startup and Message Flow**

```

```

**Sources:** [src/cli/gateway.rs105-245](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L105-L245) [src/channels/manager.rs126-164](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L126-L164) [src/channels/manager.rs159-164](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L159-L164)

### Channel Support

Gateway mode supports multiple channels configured via `config.json`. The `ChannelManager` supervises these, handling restarts and health reporting [src/channels/manager.rs39-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L39-L47)

**Sources:** [src/channels/manager.rs86-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L86-L104) [src/channels/types.rs63-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L63-L110)

## Containerized Gateway Mode

### Command Syntax

```

```

The `--containerized` flag enables per-request container isolation. Instead of processing messages directly in the gateway process, each inbound message spawns a containerized agent subprocess (via `ContainerAgentProxy`) that handles the request in an isolated environment [src/cli/gateway.rs162-204](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L162-L204)

### Architecture: Natural Language to Code Entity Mapping

This diagram maps system concepts to specific Rust structs and enums.

**Diagram: Containerized Proxy Architecture**

```

```

**Sources:** [src/cli/gateway.rs166-204](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L166-L204) [src/cli/gateway.rs63-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L63-L83)

## Tunnel Integration

### Command Syntax

```

```

The `--tunnel` flag (or `tunnel.provider` in config) starts a tunnel provider alongside the gateway to expose webhook endpoints without manual port forwarding [src/cli/gateway.rs86-102](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L86-L102)

### Supported Tunnel Providers

**Diagram: Tunnel and Webhook Integration**

```

```

**Sources:** [src/cli/gateway.rs86-102](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L86-L102) [src/tunnel/cloudflare.rs62-65](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tunnel/cloudflare.rs#L62-L65) [src/tunnel/ngrok.rs69-72](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tunnel/ngrok.rs#L69-L72) [src/tunnel/tailscale.rs73-76](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tunnel/tailscale.rs#L73-L76)

## Background Services

When running in gateway mode, several background services are orchestrated:

### Cron Service

The `CronService` manages persistent scheduled tasks. It uses a `CronStore` to track jobs and `OnMiss` policies to handle executions missed while the gateway was offline [src/cron/mod.rs235-240](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L235-L240)

- Schedules : Supports At , Every , and Cron (standard 5-field syntax) src/cron/mod.rs 19-23
- Jitter : Applies a random-ish delay using system clock nanoseconds to prevent thundering herds src/cron/mod.rs 212-221
- Error Backoff : Implements an exponential backoff schedule for consecutive errors (30s, 1m, 5m, 15m, 60m) src/cron/mod.rs 87-93

### Heartbeat Service

The `HeartbeatService` periodically checks a `HEARTBEAT.md` file in the workspace. If the file contains actionable items (checked via `is_empty`), it enqueues a `HEARTBEAT_PROMPT` to the `MessageBus` [src/heartbeat/service.rs67-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L67-L98)

- Failure Tracking : Tracks consecutive_failures and reports health status src/heartbeat/service.rs 178-186
- Actionability Logic : The is_empty function ignores comments, empty lines, and unchecked task markers ( - [ ] ) src/heartbeat/service.rs 188-200

### Startup Guard

To prevent crash loops, the gateway includes a `StartupGuard`. If consecutive crashes exceed the `crash_threshold` within a time window, the gateway enters **degraded mode**, disabling sensitive tools like `shell` and `write_file` [src/cli/gateway.rs37-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L37-L61)

## Configuration Reference

### Gateway Section

### Container Agent Section

**Sources:** [src/cli/gateway.rs34-102](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L34-L102) [src/cron/mod.rs17-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L17-L57) [src/heartbeat/service.rs16-64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L16-L64) [src/heartbeat/service.rs188-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L188-L200)
