docs(gateway): document autoApproveNodes configuration
Add comprehensive documentation for the new gateway.nodes.autoApprove feature: - New section in configuration.md covering: - Full gateway.nodes config with browser, commands, and autoApprove - Field reference table with defaults and descriptions - Security considerations and defense-in-depth explanation - Practical examples for Kubernetes and local development - Updated pairing.md with: - Expanded auto-approval section covering both mechanisms - Configuration-based auto-approval example - Security layers explanation - Cross-reference to configuration docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Rodrigo Uroz
parent
321824589d
commit
55c6b8efb7
@ -2990,6 +2990,127 @@ CLAWDBOT_STATE_DIR=~/.clawdbot-a \
|
||||
moltbot gateway --port 19001
|
||||
```
|
||||
|
||||
### `gateway.nodes` (Node management)
|
||||
|
||||
Configure node-related behavior including browser proxy routing, command allowlists, and auto-approval for node pairing.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
nodes: {
|
||||
// Browser proxy routing (for remote browser control via nodes)
|
||||
browser: {
|
||||
mode: "auto", // "auto" | "manual" | "off"
|
||||
node: "living-room-ipad" // pin a specific node (optional)
|
||||
},
|
||||
// Command allowlist/denylist for node-invoked commands
|
||||
allowCommands: ["system.run", "browser.*"],
|
||||
denyCommands: ["system.run.sudo"],
|
||||
// Auto-approval for node pairing (see below)
|
||||
autoApprove: {
|
||||
enabled: false,
|
||||
roles: ["node"],
|
||||
ipAllowlist: ["10.0.0.0/8"],
|
||||
requireToken: true,
|
||||
auditLog: true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `gateway.nodes.autoApprove` (Auto-approval for node pairing)
|
||||
|
||||
Allows trusted nodes to connect without manual approval. Useful for automated deployments (e.g., Kubernetes pods, CI runners) where interactive approval is impractical.
|
||||
|
||||
**Security:** This feature is disabled by default and implements defense-in-depth with multiple independent checks that must all pass.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
nodes: {
|
||||
autoApprove: {
|
||||
// Master switch - must be explicitly enabled
|
||||
enabled: true,
|
||||
// Roles that can be auto-approved (e.g., ["node"])
|
||||
// SECURITY: "operator" should typically NOT be included
|
||||
roles: ["node"],
|
||||
// IP CIDR allowlist - only these networks are auto-approved
|
||||
// If empty/unset, only localhost (127.0.0.1, ::1) is allowed
|
||||
ipAllowlist: [
|
||||
"10.0.0.0/8", // Private Class A
|
||||
"172.16.0.0/12", // Private Class B
|
||||
"192.168.0.0/16" // Private Class C
|
||||
],
|
||||
// Require valid gateway token for auto-approval (default: true)
|
||||
// SECURITY: Should almost always be true
|
||||
requireToken: true,
|
||||
// Log all auto-approved pairings for audit trail (default: true)
|
||||
auditLog: true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Field reference:
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `enabled` | `false` | Master switch for auto-approval. Secure default is off. |
|
||||
| `roles` | `[]` | Roles that can be auto-approved. Empty means no roles. |
|
||||
| `ipAllowlist` | `[]` | CIDR ranges for allowed IPs. Empty means localhost only. |
|
||||
| `requireToken` | `true` | Require valid gateway token. Should almost always be true. |
|
||||
| `auditLog` | `true` | Log auto-approvals with device ID, role, IP, and client info. |
|
||||
|
||||
**Security considerations:**
|
||||
|
||||
- **Disabled by default**: Requires explicit opt-in via `enabled: true`.
|
||||
- **Role restrictions**: Only roles in the `roles` array are auto-approved. Keep `operator` out unless you have a specific need.
|
||||
- **IP allowlist**: If not configured, only localhost connections are auto-approved. Use CIDR notation for network ranges.
|
||||
- **Token validation**: With `requireToken: true` (default), the connecting node must present a valid gateway token.
|
||||
- **Audit logging**: When `auditLog: true` (default), all non-localhost auto-approvals are logged with full context for security review.
|
||||
|
||||
**Example: Kubernetes cluster**
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
nodes: {
|
||||
autoApprove: {
|
||||
enabled: true,
|
||||
roles: ["node"],
|
||||
ipAllowlist: ["10.244.0.0/16"], // Kubernetes pod CIDR
|
||||
requireToken: true,
|
||||
auditLog: true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example: Local development (localhost only)**
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
nodes: {
|
||||
autoApprove: {
|
||||
enabled: true,
|
||||
roles: ["node"],
|
||||
// No ipAllowlist = localhost only (127.0.0.1, ::1)
|
||||
requireToken: false // OK for local dev
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Related docs:
|
||||
- [Gateway pairing](/gateway/pairing)
|
||||
- [Nodes CLI](/cli/nodes)
|
||||
- [Gateway security](/gateway/security)
|
||||
|
||||
### `hooks` (Gateway webhooks)
|
||||
|
||||
Enable a simple HTTP webhook endpoint on the Gateway HTTP server.
|
||||
|
||||
@ -64,13 +64,47 @@ Notes:
|
||||
`node.pair.request`.
|
||||
- Requests may include `silent: true` as a hint for auto-approval flows.
|
||||
|
||||
## Auto-approval (macOS app)
|
||||
## Auto-approval
|
||||
|
||||
Auto-approval allows trusted nodes to connect without manual intervention. There are two mechanisms:
|
||||
|
||||
### macOS app (SSH verification)
|
||||
|
||||
The macOS app can optionally attempt a **silent approval** when:
|
||||
- the request is marked `silent`, and
|
||||
- the app can verify an SSH connection to the gateway host using the same user.
|
||||
|
||||
If silent approval fails, it falls back to the normal “Approve/Reject” prompt.
|
||||
If silent approval fails, it falls back to the normal "Approve/Reject" prompt.
|
||||
|
||||
### Configuration-based auto-approval
|
||||
|
||||
For automated deployments (Kubernetes, CI runners, etc.), you can configure the gateway to auto-approve nodes based on role, IP address, and token validation.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
nodes: {
|
||||
autoApprove: {
|
||||
enabled: true,
|
||||
roles: ["node"], // Only auto-approve "node" role
|
||||
ipAllowlist: ["10.0.0.0/8"], // Only from private network
|
||||
requireToken: true, // Must have valid gateway token
|
||||
auditLog: true // Log all auto-approvals
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Security layers (all must pass):**
|
||||
1. `enabled: true` - Feature must be explicitly enabled
|
||||
2. Role must be in `roles` array
|
||||
3. Client IP must match `ipAllowlist` (or be localhost if empty)
|
||||
4. Valid gateway token required (when `requireToken: true`)
|
||||
|
||||
Localhost connections (127.0.0.1, ::1) are always auto-approved for backward compatibility.
|
||||
|
||||
See [gateway.nodes.autoApprove](/gateway/configuration#gatewaynodes-node-management) for the full configuration reference.
|
||||
|
||||
## Storage (local, private)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user