77 lines
2.0 KiB
Markdown
77 lines
2.0 KiB
Markdown
 
|
# How to Secure a Local AI Agent with nanobot
|
||
|
|
|
||
|
|
This guide covers the practical controls to review before letting a nanobot
|
||
|
|
agent access files, shell commands, web fetch, chat apps, or remote users.
|
||
|
|
|
||
|
|
## What you will build
|
||
|
|
|
||
|
|
- a workspace-scoped agent setup
|
||
|
|
- narrow channel access
|
||
|
|
- safer secrets handling
|
||
|
|
- optional shell sandboxing on Linux
|
||
|
|
|
||
|
|
## When to use this
|
||
|
|
|
||
|
|
Use this before exposing nanobot to teammates, chat apps, public networks, broad
|
||
|
|
web access, or unattended automations.
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python -m pip install nanobot-ai
|
||
|
|
nanobot onboard --wizard
|
||
|
|
nanobot agent -m "Hello!"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Minimal working example
|
||
|
|
|
||
|
|
Start with workspace restriction:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"tools": {
|
||
|
|
"restrictToWorkspace": true,
|
||
|
|
"exec": {
|
||
|
|
"enable": true,
|
||
|
|
"sandbox": "bwrap"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
`bwrap` is Linux-only and requires bubblewrap. On macOS or Windows, keep
|
||
|
|
`restrictToWorkspace` enabled and review shell access carefully.
|
||
|
|
|
||
|
|
## Production notes
|
||
|
|
|
||
|
|
- Use environment variables for provider keys, bot tokens, and mailbox
|
||
|
|
passwords.
|
||
|
|
- Keep one workspace per trust boundary.
|
||
|
|
- Use `allowFrom`, pairing, and mention-only group policy for chat apps.
|
||
|
|
- Bind WebUI, WebSocket, and API services to localhost unless remote access is
|
||
|
|
intentional.
|
||
|
|
|
||
|
|
## Security notes
|
||
|
|
|
||
|
|
- `restrictToWorkspace` is an application-level guard, not an OS sandbox.
|
||
|
|
- `tools.exec.enable: false` removes shell execution entirely.
|
||
|
|
- HTTP web fetch and HTTP MCP use SSRF protections by default.
|
||
|
|
- Adding broad `tools.ssrfWhitelist` ranges increases exposure.
|
||
|
|
- `allowFrom: ["*"]` means anyone who can reach that channel can talk to the
|
||
|
|
bot.
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
- If a needed file cannot be read, confirm the active workspace path.
|
||
|
|
- If a shell command fails under `bwrap`, check whether the command needs files
|
||
|
|
outside the sandbox.
|
||
|
|
- If local HTTP tools are blocked, review the SSRF whitelist and use a narrow
|
||
|
|
CIDR.
|
||
|
|
|
||
|
|
## Related nanobot docs
|
||
|
|
|
||
|
|
- [Configuration: Security](../configuration.md#security)
|
||
|
|
- [Pairing](../configuration.md#pairing)
|
||
|
|
- [Deployment](../deployment.md)
|
||
|
|
- [Chat Apps](../chat-apps.md)
|