interactive-story/planning/DECISIONS/011-local-inference-endpoint-policy.md

ADR 011 — Local Inference Endpoint Policy

Status: Accepted
Date: 2026-09-02
Implemented in: M2, backend/app/endpoints.py

Decision

v1 supports Ollama only, and will send a story to an inference endpoint only when every address that endpoint resolves to lies inside an explicit allowlist of local networks.

• The storyteller UI/API remains loopback-bound by default. Configuring a LAN inference endpoint does not change where the storyteller listens.
• Inference may use same-host loopback (the default) or an explicitly configured trusted-LAN/local-network address.
• Public Internet addresses are denied.
• The policy is address-based, using explicit allowed CIDRs rather than Python's generic is_private / is_reserved classifications.
• Every resolved address must be allowed; one address outside the allowlist refuses the endpoint.
• The policy is checked on configuration and again before every request.
• TLS verification is mandatory for HTTPS and is never traded against this policy.
• Arbitrary cloud / OpenAI-compatible endpoints are intentionally outside v1.

Context

The endpoint setting is the most consequential in the application. The storyteller sends the player's prose, the assembled context, the retrieved memories and the embedding inputs to whatever address it names: point it somewhere else and the whole campaign goes there.

The inherited AI-DnD guard could not be reused, because its rule is the opposite of this product's. AI-DnD was a hosted service, so its SSRF guard blocked private addresses to stop a user reaching the server's internal network. A local storyteller must do exactly the reverse — permit the private ranges and refuse the public Internet. The guard was removed rather than adapted.

Alternatives Considered

• Hostname matching / a denylist of cloud providers. Rejected as the primary rule: it is trivially talked around by spelling a name differently, by a CNAME, or by a private DNS entry pointing at a public host. A denylist of known cloud hostnames is retained, but only to make the error message explain why — the address rule already refuses all of them.
• Python's is_private / is_reserved. Rejected; see below.
• Loopback-only inference. Rejected: trusted-LAN inference is accepted production behaviour under ADR 002, and a great many users will run Ollama on the one machine in the house that has a GPU.
• UI-only discouragement. Rejected: a setting that is merely absent from a dropdown is still reachable by editing the database.

Reason for Explicit CIDRs

Generic address classifications do not answer this project's security question, and get it wrong in both directions for addresses this application actually sees:

• is_private is true of the documentation ranges and of 0.0.0.0/8, neither of which is a user's LAN;
• is_reserved is true of IPv6 loopback, so a rule written around it refuses http://[::1]:11434/v1 — an ordinary same-host Ollama.

Naming the networks keeps the policy readable, makes it auditable against this document, and makes anything unnamed refused by default:

127.0.0.0/8     this machine          ::1/128     this machine, v6
10.0.0.0/8      RFC1918               fc00::/7    unique-local, v6
172.16.0.0/12   RFC1918               fe80::/10   link-local, v6
192.168.0.0/16  RFC1918
169.254.0.0/16  link-local
100.64.0.0/10   carrier-grade NAT, which mesh VPNs such as Tailscale use

Carrier-grade NAT is included deliberately: it is what a mesh VPN such as Tailscale hands out, and such a network is as user-controlled as a LAN.

Consequences

• Validation runs in two places — routers/settings.py on save and on the connection test, and providers/openai_compatible.py before the generate, chat and embedding requests. Configuration validation alone is not sufficient, and a database edited behind the settings API must not become a way out.
• Because a hostname is resolved at check time, an endpoint given as a literal address behaves most predictably.
• No cloud provider can be configured, so no API-key storage is needed. M2 removed both.
• The error strings are user-facing and say what to do, not what failed internally.

Accepted Residual Risks

Documented rather than mitigated, and not M3 work:

1. A hostile host on a trusted LAN is inside the permitted boundary. The policy authorizes an address range, not a machine. If an attacker already controls a device on the user's network and the user points the storyteller at it, the story goes there. The defence is the inference host's own firewall and network policy.
2. A DNS-rebinding interval exists between the policy's resolution of a hostname and the HTTP client's own connection. The two resolutions are separate, so a name that answers with a LAN address for the check and a public address for the connection is theoretically possible. Using a literal address closes it entirely.

Scope

This ADR covers which inference endpoints the product will talk to. It is not a general remote-access design: it says nothing about exposing the storyteller itself beyond loopback, which remains out of scope for v1.

References

• SECURITY-THREAT-MODEL.md §10A, §71A item 5, §77
• TECHNICAL-DESIGN.md §5.1 item 4, §5.2
• ADR 002 (Ollama-only, and the TLS consequence), ADR 004 (local-only production)
• planning/archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md §F, §K.1