feat(gateway): add background and service controls
This commit is contained in:
Xubin Ren
+29
-4
@@ -12,7 +12,7 @@ Use this page when you know what you want to run and need the command shape. For
|
||||
| Check config without calling a model | `nanobot status` | Reads the default config and summarizes the active model/provider |
|
||||
| Send one test message | `nanobot agent -m "Hello!"` | First proof that install, config, provider, model, and workspace all work |
|
||||
| Chat in the terminal | `nanobot agent` | Interactive local chat; exit with `exit`, `/exit`, `:q`, or `Ctrl+D` |
|
||||
| Use WebUI or chat apps | `nanobot gateway` | Keep this terminal running while those surfaces are in use |
|
||||
| Use WebUI or chat apps | `nanobot gateway` | Keep this terminal running, or use `nanobot gateway --background` |
|
||||
| Serve an OpenAI-compatible API | `nanobot serve` | Starts `/v1/chat/completions`, `/v1/models`, and `/health` |
|
||||
| Check chat channel setup | `nanobot channels status` | Useful before starting `nanobot gateway` |
|
||||
| Log in to QR/OAuth-style channels | `nanobot channels login <channel>` | Used by channels such as WhatsApp and WeChat |
|
||||
@@ -46,7 +46,9 @@ nanobot gateway --verbose
|
||||
nanobot serve --verbose
|
||||
```
|
||||
|
||||
Long-running commands keep working until you stop them. Press `Ctrl+C` in that terminal to stop `nanobot gateway` or `nanobot serve`.
|
||||
Long-running commands keep working until you stop them. Press `Ctrl+C` in that terminal
|
||||
to stop foreground `nanobot gateway` or `nanobot serve`. If you started the gateway
|
||||
with `--background`, use `nanobot gateway stop`.
|
||||
|
||||
## Setup
|
||||
|
||||
@@ -79,15 +81,38 @@ Interactive mode exits with `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`.
|
||||
|
||||
## Gateway
|
||||
|
||||
`nanobot gateway` starts enabled chat channels, WebUI/WebSocket when configured, cron-backed system jobs, Dream, heartbeat, and the health endpoint.
|
||||
`nanobot gateway` starts enabled chat channels, WebUI/WebSocket when configured, cron-backed system jobs, Dream, heartbeat, and the health endpoint. By default it runs in the foreground, which keeps existing scripts and terminal workflows unchanged. Use `--background` when you want a local macOS, Linux, or Windows process that you can manage from the CLI.
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `nanobot gateway` | Start the gateway with config defaults |
|
||||
| `nanobot gateway` | Start the gateway in the foreground with config defaults |
|
||||
| `nanobot gateway --verbose` | Show verbose runtime output |
|
||||
| `nanobot gateway --port <port>` | Override `gateway.port` for the health endpoint |
|
||||
| `nanobot gateway --workspace <path>` | Override workspace |
|
||||
| `nanobot gateway --config <path>` | Use a specific config file |
|
||||
| `nanobot gateway --background` | Start the gateway as a background process |
|
||||
| `nanobot gateway status` | Show the recorded background gateway PID, state file, and log file |
|
||||
| `nanobot gateway logs --no-follow` | Print recent background gateway logs and exit |
|
||||
| `nanobot gateway logs` | Follow background gateway logs |
|
||||
| `nanobot gateway restart` | Restart the recorded background gateway with the current config |
|
||||
| `nanobot gateway stop` | Stop the recorded background gateway |
|
||||
| `nanobot gateway install-service` | Install a systemd user service or macOS LaunchAgent |
|
||||
| `nanobot gateway install-service --dry-run` | Preview the generated service file and system commands |
|
||||
| `nanobot gateway uninstall-service` | Remove the installed system service |
|
||||
|
||||
For custom instances, pass the same selector flags to management commands:
|
||||
|
||||
```bash
|
||||
nanobot gateway --background --config ./bot-a/config.json --workspace ./bot-a/workspace
|
||||
nanobot gateway status --config ./bot-a/config.json --workspace ./bot-a/workspace
|
||||
nanobot gateway stop --config ./bot-a/config.json --workspace ./bot-a/workspace
|
||||
nanobot gateway install-service --config ./bot-a/config.json --workspace ./bot-a/workspace --name bot-a
|
||||
```
|
||||
|
||||
`--background` is a lightweight detached process. `install-service` is for
|
||||
login/startup integration: Linux uses a systemd user service; macOS uses a
|
||||
LaunchAgent plist. System services run the foreground gateway under the OS
|
||||
supervisor rather than nesting another background process.
|
||||
|
||||
Default health endpoint:
|
||||
|
||||
|
||||
+40
-79
@@ -106,48 +106,41 @@ docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot status
|
||||
|
||||
Run the gateway as a systemd user service so it starts automatically and restarts on failure.
|
||||
|
||||
**1. Find the nanobot binary path:**
|
||||
Preview the generated unit first:
|
||||
|
||||
```bash
|
||||
which nanobot # e.g. /home/user/.local/bin/nanobot
|
||||
nanobot gateway install-service --manager systemd --dry-run
|
||||
```
|
||||
|
||||
**2. Create the service file** at `~/.config/systemd/user/nanobot-gateway.service` (replace `ExecStart` path if needed):
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Nanobot Gateway
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=%h/.local/bin/nanobot gateway
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
NoNewPrivileges=yes
|
||||
ProtectSystem=strict
|
||||
ReadWritePaths=%h
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
**3. Enable and start:**
|
||||
Install, enable, and start it:
|
||||
|
||||
```bash
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now nanobot-gateway
|
||||
nanobot gateway install-service --manager systemd
|
||||
```
|
||||
|
||||
**Common operations:**
|
||||
For a custom instance, pass the same config/workspace selector you use to run the gateway:
|
||||
|
||||
```bash
|
||||
nanobot gateway install-service \
|
||||
--manager systemd \
|
||||
--name nanobot-telegram \
|
||||
--config ~/.nanobot-telegram/config.json \
|
||||
--workspace ~/.nanobot-telegram/workspace
|
||||
```
|
||||
|
||||
Common operations:
|
||||
|
||||
```bash
|
||||
systemctl --user status nanobot-gateway # check status
|
||||
systemctl --user restart nanobot-gateway # restart after config changes
|
||||
journalctl --user -u nanobot-gateway -f # follow logs
|
||||
nanobot gateway uninstall-service --manager systemd
|
||||
```
|
||||
|
||||
If you edit the `.service` file itself, run `systemctl --user daemon-reload` before restarting.
|
||||
The installer writes `~/.config/systemd/user/nanobot-gateway.service`, runs
|
||||
`systemctl --user daemon-reload`, enables the unit, and restarts it. It uses the
|
||||
current Python executable with `python -m nanobot gateway --foreground`, so the
|
||||
service runs in the same environment you used to install nanobot.
|
||||
|
||||
> **Note:** User services only run while you are logged in. To keep the gateway running after logout, enable lingering:
|
||||
>
|
||||
@@ -159,70 +152,38 @@ If you edit the `.service` file itself, run `systemctl --user daemon-reload` bef
|
||||
|
||||
Use a LaunchAgent when you want `nanobot gateway` to stay online after you log in, without keeping a terminal open.
|
||||
|
||||
**1. Get the absolute `nanobot` path:**
|
||||
Preview the generated plist first:
|
||||
|
||||
```bash
|
||||
which nanobot # e.g. /Users/youruser/.local/bin/nanobot
|
||||
nanobot gateway install-service --manager launchd --dry-run
|
||||
```
|
||||
|
||||
Use that exact path in the plist. It keeps the Python environment from your install method.
|
||||
|
||||
**2. Create `~/Library/LaunchAgents/ai.nanobot.gateway.plist`:**
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>ai.nanobot.gateway</string>
|
||||
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/Users/youruser/.local/bin/nanobot</string>
|
||||
<string>gateway</string>
|
||||
<string>--workspace</string>
|
||||
<string>/Users/youruser/.nanobot/workspace</string>
|
||||
</array>
|
||||
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/Users/youruser/.nanobot/workspace</string>
|
||||
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
|
||||
<key>KeepAlive</key>
|
||||
<dict>
|
||||
<key>SuccessfulExit</key>
|
||||
<false/>
|
||||
</dict>
|
||||
|
||||
<key>StandardOutPath</key>
|
||||
<string>/Users/youruser/.nanobot/logs/gateway.log</string>
|
||||
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/Users/youruser/.nanobot/logs/gateway.error.log</string>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
**3. Load and start it:**
|
||||
Install, load, enable, and start it:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/Library/LaunchAgents ~/.nanobot/logs
|
||||
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.nanobot.gateway.plist
|
||||
launchctl enable gui/$(id -u)/ai.nanobot.gateway
|
||||
launchctl kickstart -k gui/$(id -u)/ai.nanobot.gateway
|
||||
nanobot gateway install-service --manager launchd
|
||||
```
|
||||
|
||||
**Common operations:**
|
||||
For a custom instance:
|
||||
|
||||
```bash
|
||||
nanobot gateway install-service \
|
||||
--manager launchd \
|
||||
--name nanobot-telegram \
|
||||
--config ~/.nanobot-telegram/config.json \
|
||||
--workspace ~/.nanobot-telegram/workspace
|
||||
```
|
||||
|
||||
Common operations:
|
||||
|
||||
```bash
|
||||
launchctl list | grep ai.nanobot.gateway
|
||||
launchctl kickstart -k gui/$(id -u)/ai.nanobot.gateway # restart
|
||||
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.nanobot.gateway.plist
|
||||
launchctl kickstart -k gui/$(id -u)/ai.nanobot.gateway
|
||||
nanobot gateway uninstall-service --manager launchd
|
||||
```
|
||||
|
||||
After editing the plist, run `launchctl bootout ...` and `launchctl bootstrap ...` again.
|
||||
The installer writes `~/Library/LaunchAgents/ai.nanobot.gateway.plist`, uses the
|
||||
current Python executable with `python -m nanobot gateway --foreground`, and
|
||||
writes LaunchAgent logs under `~/.nanobot/logs/`.
|
||||
|
||||
> **Note:** if startup fails with "address already in use", stop the manually started `nanobot gateway` process first.
|
||||
|
||||
Reference in New Issue
Block a user