opencode/picoclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gateway): document fallback behavior and allowed CIDRs

Browse source
This commit is contained in:
Sakurapainting 2026-04-02 18:02:46 +08:00
parent f6323f1d23
commit 8c1b1feaad
3 changed files with 37 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -242,7 +242,7 @@ docker compose -f docker/docker-compose.yml --profile launcher up -d
# Open http://localhost:18800
```
> **Docker / VM users:** The Gateway listens on `127.0.0.1` by default. Set `PICOCLAW_GATEWAY_HOST=0.0.0.0` or use the `-public` flag to make it accessible from the host.
> **Docker / VM users:** The Gateway listens on `127.0.0.1` by default. Set `PICOCLAW_GATEWAY_HOST=0.0.0.0` or use the `-public` flag to make it accessible from the host. If loopback bind fails at runtime, PicoClaw may fallback to `0.0.0.0` with CIDR restrictions; configure `gateway.allowed_cidrs` to keep exposure limited.
```bash
# Check logs

33
docs/configuration.md
View file

@ -49,6 +49,39 @@ When omitted, the default is `warn`. Supported values: `debug`, `info`, `warn`,
You can also override this with the environment variable `PICOCLAW_LOG_LEVEL`.
### Gateway Host Fallback And CIDR Allowlist
`gateway.host` defaults to `127.0.0.1`.
When `gateway.host` is a loopback address (`127.0.0.1`, `::1`, or `localhost`) and bind fails (for example, on boards where loopback is unavailable), PicoClaw automatically:
1. Scans non-loopback network interfaces and collects local CIDR ranges.
2. Falls back to bind on `0.0.0.0`.
3. Enforces a CIDR allowlist for gateway HTTP endpoints.
CIDR sources in fallback mode:
- If `gateway.allowed_cidrs` is configured, that list is used.
- If `gateway.allowed_cidrs` is empty, discovered local CIDRs are used.
- If no non-loopback CIDR can be discovered, gateway startup fails.
Loopback clients are always allowed for local administration.
Example:
```json
{
"gateway": {
"host": "127.0.0.1",
"port": 18790,
"allowed_cidrs": [
"192.168.1.0/24",
"10.0.0.0/8"
]
}
}
```
### Workspace Layout
PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):

3
docs/docker.md
View file

@ -26,6 +26,9 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
> [!TIP]
> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
> [!TIP]
> If `gateway.host` is loopback and bind fails at runtime (for example, loopback unavailable on some boards), PicoClaw will fallback to `0.0.0.0` and enforce CIDR restrictions. Configure `gateway.allowed_cidrs` to keep exposure limited to trusted networks.
> [!NOTE]
> The `gateway` profile only serves the webhook handlers (including Pico when enabled) and health endpoints on the gateway port, so it does not expose generic REST chat endpoints such as `/chat` or `/a2a`. Launcher mode adds the browser UI plus `/api/pico/token` and a `/pico/ws` proxy on the launcher port, but `/pico/ws` is also available directly on the gateway whenever the Pico channel is enabled.