How to Secure a Local AI Agent: Token, Loopback, File Roots, Allow-Lists

A local agent is software on your machine that can read files and, if you let it, make network requests. Running it locally removes one category of risk — your documents are not on somebody else's server — and adds another: it is on the same machine as everything else you have.

Four controls decide what it can reach. OpenClerq sets all four to sensible defaults as of release 0.4, but defaults are only useful if you know what they are.

1. The gateway is authenticated

Every endpoint except /health requires a bearer token, generated on first run at ~/.clerq/gateway-token and compared in constant time. There is no development bypass — that was the point of the 0.4 release, and it is a breaking change from earlier versions on purpose.

# no token: refused$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18790/skills401# bound to loopback only — not reachable from the network$ lsof -nP -iTCP:18790 -sTCP:LISTENnode    41822  you   22u  IPv4  TCP 127.0.0.1:18790 (LISTEN)# the token is a credential — check nothing else can read it$ ls -l ~/.clerq/gateway-token-rw-------  1 you  staff  64  8 Sep 09:12 gateway-token

2. It listens on loopback

The listener binds 127.0.0.1 unless you deliberately change it. That means nothing on your network can reach it — not a colleague, not a compromised smart device, not someone on the café wifi. If you ever bind it to `0.0.0.0` to reach it from another machine, you have just published a tool-execution API. Put it behind a tunnel instead.

3. File reads are confined to a root

The fs.read tool resolves every path against a realpath-ed root and refuses anything that escapes it — traversal, absolute or UNC paths, NUL bytes, symlinks pointing outside, non-regular files, and anything over the read cap. It also refuses a sibling directory that merely shares a prefix, which is a check that did not exist before 0.4.

1
2
3
4
5
6{  "fsRoot": "/Users/you/clerq-workspace",  "fsMaxReadBytes": 1048576,  "symlinkPolicy": "refuse-outside-root",  "httpAllowlist": []}

4. Outbound HTTP is off by default

The http.request tool is disabled until httpAllowlist names specific hosts. When enabled, private, link-local and cloud-metadata addresses are blocked on every redirect hop, not just the first — which is what stops a redirect chain being used to reach an internal service or an instance metadata endpoint.

1. 1.Confirm /skills returns 401 without a token.
2. 2.Confirm the listener shows 127.0.0.1, not * or 0.0.0.0.
3. 3.Point fsRoot at a dedicated workspace directory and check the permissions on it.
4. 4.Leave httpAllowlist empty until something genuinely needs it, then add one host.
5. 5.Put the skills directory in version control and review changes.