gateway - nanobot

Usage

nanobot gateway [OPTIONS]

Description

The gateway command starts the nanobot background service that handles:

Message routing between channels and the agent
Channel connections (WhatsApp, Telegram, Discord, etc.)
Scheduled tasks (cron jobs)
Heartbeat monitoring (proactive notifications)
Session management (persistent conversations)

This is the main service for running nanobot as a chat application.

Options

--port

integer

Port number for the gateway service.

nanobot gateway --port 8080

Required: No
Default: 18790

--workspace

string

Workspace directory path. Overrides the workspace setting in config.json.

nanobot gateway --workspace /path/to/workspace

Required: No
Default: From config.json or ~/.nanobot/workspace/

--config

string

Path to configuration file.

nanobot gateway --config /etc/nanobot/config.json

Required: No
Default: ~/.nanobot/config.json

--verbose

boolean

Enable verbose debug logging.

nanobot gateway --verbose

Required: No
Default: false

Examples

Basic Start

nanobot gateway

Output:

🐈 Starting nanobot gateway on port 18790...
[green]✓[/green] Channels enabled: telegram, whatsapp
[green]✓[/green] Cron: 3 scheduled jobs
[green]✓[/green] Heartbeat: every 3600s

Custom Port

nanobot gateway --port 8080

Debug Mode

nanobot gateway --verbose

Shows detailed logs:

DEBUG:nanobot.channels.telegram:Polling for updates...
DEBUG:nanobot.agent.loop:Processing message from telegram:123456
DEBUG:nanobot.agent.tools:Using tool: web_search

Custom Workspace

nanobot gateway --workspace /mnt/data/nanobot

Production Deployment

nanobot gateway \
  --config /etc/nanobot/config.json \
  --workspace /var/lib/nanobot \
  --port 18790

Gateway Components

1. Message Bus

Routes messages between channels and the agent:

[Channel] -> [Inbound Queue] -> [Agent] -> [Outbound Queue] -> [Channel]

2. Agent Loop

Processes incoming messages:

Maintains conversation context
Executes tools
Generates responses
Manages memory

3. Channel Manager

Manages active channel connections:

WhatsApp (WebSocket bridge)
Telegram (polling)
Discord (WebSocket gateway)
Slack (Socket Mode)
Email (IMAP/SMTP)
DingTalk, Feishu, QQ, Mochat

4. Cron Service

Executes scheduled tasks:

Reminders
Recurring reports
Automated workflows

Stored in: ~/.nanobot/cron/jobs.json

5. Heartbeat Service

Proactive monitoring and notifications:

Checks system status
Sends periodic updates
Triggers alerts

Interval: Configurable (default 3600s)

6. Session Manager

Tracks active conversations:

Per-channel sessions
Message history
User context
Agent memory

Stored in: ~/.nanobot/workspace/sessions/

Configuration

The gateway uses ~/.nanobot/config.json:

{
  "gateway": {
    "heartbeat": {
      "enabled": true,
      "interval_s": 3600
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    },
    "whatsapp": {
      "enabled": true,
      "bridge_url": "ws://localhost:3001"
    }
  }
}

See Configuration for all options.

Startup Sequence

Load configuration from file
Sync workspace templates (SOUL.md, TOOLS.md, etc.)
Initialize message bus
Create provider (API client)
Start session manager
Initialize cron service and load jobs
Create agent loop with tools
Start channel manager for enabled channels
Start heartbeat service
Begin event loop

Channel Status

On startup, the gateway displays enabled channels:

[green]✓[/green] Channels enabled: telegram, discord, email

If no channels are enabled:

[yellow]Warning: No channels enabled[/yellow]

Check channel status:

nanobot channels status

Cron Status

If scheduled jobs exist:

[green]✓[/green] Cron: 5 scheduled jobs

View jobs:

cat ~/.nanobot/cron/jobs.json

Heartbeat Configuration

Heartbeat interval is shown on startup:

[green]✓[/green] Heartbeat: every 3600s

Configure in config.json:

{
  "gateway": {
    "heartbeat": {
      "enabled": true,
      "interval_s": 1800  # 30 minutes
    }
  }
}

Graceful Shutdown

The gateway handles shutdown signals:

# Press Ctrl+C
^C
Shutting down...

Cleanup sequence:

Stop agent loop
Close MCP connections
Stop heartbeat service
Stop cron service
Disconnect all channels
Save session state

Signal Handling

SIGINT (Ctrl+C): Graceful shutdown
SIGTERM: Graceful shutdown
SIGHUP: Graceful shutdown

Running as Service

systemd (Linux)

Create /etc/systemd/system/nanobot.service:

[Unit]
Description=Nanobot Gateway
After=network.target

[Service]
Type=simple
User=nanobot
WorkingDirectory=/home/nanobot
ExecStart=/usr/local/bin/nanobot gateway
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable nanobot
sudo systemctl start nanobot
sudo systemctl status nanobot

Docker

Create Dockerfile:

FROM python:3.11-slim

RUN pip install nanobot

COPY config.json /root/.nanobot/config.json

EXPOSE 18790

CMD ["nanobot", "gateway"]

Build and run:

docker build -t nanobot .
docker run -d -p 18790:18790 \
  -v ~/.nanobot:/root/.nanobot \
  --name nanobot \
  nanobot

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  nanobot:
    image: nanobot:latest
    ports:
      - "18790:18790"
    volumes:
      - ~/.nanobot:/root/.nanobot
    restart: unless-stopped
    environment:
      - BRIDGE_TOKEN=${BRIDGE_TOKEN}

Run:

docker-compose up -d

PM2 (Node.js Process Manager)

pm2 start "nanobot gateway" --name nanobot
pm2 save
pm2 startup

Monitoring

Check Status

# systemd
sudo systemctl status nanobot

# Docker
docker logs -f nanobot

# PM2
pm2 logs nanobot

Resource Usage

# systemd
systemctl show nanobot -p MemoryCurrent -p CPUUsageNSec

# Docker
docker stats nanobot

Health Check

Create a health check endpoint or use:

nanobot status

Troubleshooting

Port Already in Use

Error: Address already in use: 18790

Solution:

# Find process using port
lsof -i :18790

# Use different port
nanobot gateway --port 18791

Channel Connection Failed

[red]Failed to connect to Telegram[/red]

Solution:

Check token in config.json
Verify network connectivity
Check API status
Enable verbose logging: --verbose

MCP Server Error

[red]MCP server 'filesystem' failed to start[/red]

Solution:

Check MCP configuration
Verify server binary exists
Check permissions
Review logs with --verbose

Out of Memory

Killed

Solution:

Reduce memory_window in config
Limit max_tokens
Increase system memory
Use lighter model

Performance Tuning

Reduce Memory Usage

{
  "agents": {
    "defaults": {
      "memory_window": 10,  // Lower = less memory
      "max_tokens": 2048    // Lower = less memory
    }
  }
}

Faster Response Times

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-3.5-turbo",  // Faster model
      "temperature": 0.3                  // Less creative = faster
    }
  }
}

Optimize Heartbeat

{
  "gateway": {
    "heartbeat": {
      "enabled": false  // Disable if not needed
    }
  }
}

Exit Codes

0: Clean shutdown
1: Error (configuration, network, API)
130: Interrupted by user (Ctrl+C)

agent - Direct CLI interaction
channels - Manage channels
status - Check configuration
onboard - Initialize setup

CLI Commands

Agent API

Tools

Configuration Schema

​Usage

​Description

​Options

​Examples

​Basic Start

​Custom Port

​Debug Mode

​Custom Workspace

​Production Deployment

​Gateway Components

​1. Message Bus

​2. Agent Loop

​3. Channel Manager

​4. Cron Service

​5. Heartbeat Service

​6. Session Manager

​Configuration

​Startup Sequence

​Channel Status

​Cron Status

​Heartbeat Configuration

​Graceful Shutdown

​Signal Handling

​Running as Service

​systemd (Linux)

​Docker

​Docker Compose

​PM2 (Node.js Process Manager)

​Monitoring

​Check Status

​Resource Usage

​Health Check

​Troubleshooting

​Port Already in Use

​Channel Connection Failed

​MCP Server Error

​Out of Memory

​Performance Tuning

​Reduce Memory Usage

​Faster Response Times

​Optimize Heartbeat

​Exit Codes

​Related Commands

​See Also

Build docs developers (and LLMs) love

Usage

Description

Options

Examples

Basic Start

Custom Port

Debug Mode

Custom Workspace

Production Deployment

Gateway Components

1. Message Bus

2. Agent Loop

3. Channel Manager

4. Cron Service

5. Heartbeat Service

6. Session Manager

Configuration

Startup Sequence

Channel Status

Cron Status

Heartbeat Configuration

Graceful Shutdown

Signal Handling

Running as Service

systemd (Linux)

Docker

Docker Compose

PM2 (Node.js Process Manager)

Monitoring

Check Status

Resource Usage

Health Check

Troubleshooting

Port Already in Use

Channel Connection Failed

MCP Server Error

Out of Memory

Performance Tuning

Reduce Memory Usage

Faster Response Times

Optimize Heartbeat

Exit Codes

Related Commands

See Also