Network Design & Access Profiles
Relevant source files
The following files were used as context for generating this wiki page:
Nyansa uses a tiered network architecture to secure a self-hosted AI stack. The system isolates stateful backend services within a private Docker network and exposes only the Caddy reverse proxy to external traffic. Access is controlled through environment-specific "Access Profiles" that define how users reach the chat interface and workflow engine.
Sources: README.md:58-86, docker-compose.yml:1-36
Core Network Architecture
The project defines a single internal Docker network named nyansa. All backend services attach to this network to communicate. Most services do not publish any ports to the host machine, preventing direct access from outside the Docker environment.
The diagram above shows the isolation of data-handling services like Qdrant and Postgres from the external user.
Sources: README.md:88-124, docker-compose.yml:34-36
Service Exposure Rules
Security is enforced through strict port binding rules. Automated scripts verify these rules across all hardware and access profile combinations.
| Service | Host Binding | Exposure |
|---|---|---|
nyansa-postgres | None | Internal Only |
nyansa-qdrant | None | Internal Only |
nyansa-ollama | None | Internal Only |
nyansa-memory-api | None | Internal Only |
nyansa-n8n | 127.0.0.1:5678 | Loopback Only |
nyansa-open-webui | 127.0.0.1:3000 | Loopback Only |
nyansa-caddy-public | 0.0.0.0:80/443 | Publicly Accessible |
Sources: scripts/check-exposure.sh:4-10, docker-compose.yml:144-245
Access Profiles
Nyansa provides two mutually exclusive access profiles to determine how the stack is exposed to the network.
Public Profile
The public profile uses nyansa-caddy-public to serve applications over the open internet. It automates HTTPS through Let's Encrypt and adds an additional layer of HTTP Basic Auth in front of the n8n editor.
- Ports: Publishes 80 and 443 on all interfaces.
- Authentication: Requires
N8N_BASIC_AUTH_USERandN8N_BASIC_AUTH_HASH. - Components:
nyansa-caddy-public.
Sources: docker-compose.yml:312-327, README.md:43-46
Tailscale Profile
The tailscale profile provides private access via a Tailscale tailnet. This profile publishes no ports on the host machine. Instead, it uses a sidecar container to join the private network.
Caddy in this profile shares the network namespace of the Tailscale container to serve traffic exclusively on the tailnet.
Sources: docker-compose.yml:330-370, README.md:126-127
Service Isolation and Internal API Security
Backend services rely on network-level isolation and token-based authentication rather than public port exposure.
Memory API Security
The nyansa-memory-api service handles RAG operations and vault indexing. It is configured with a read-only root filesystem and no Linux capabilities.
- Authentication: Requires a Bearer token (
MEMORY_API_TOKEN) for all routes except/health. - Networking: Listens on
0.0.0.0:8080inside thenyansanetwork but publishes no host ports. - Storage Access: The Obsidian vault is mounted at
/vaultas a read-only volume.
Sources: services/memory-api/src/app.ts:51-64, services/memory-api/src/config.ts:4-15, docker-compose.yml:256-276
Database and Vector Store Access
Stateful services like Qdrant and PostgreSQL are only reachable by other containers on the internal network.
- Qdrant: Protected by
QDRANT_API_KEY. n8n receives this key at runtime viaCREDENTIALS_OVERWRITE_DATA. - Postgres: Only reachable by
nyansa-n8nandnyansa-n8n-import.
Sources: docker-compose.yml:61-63, docker-compose.yml:184-187, README.md:144-150
Validation Scripts
The system includes a verification script, scripts/check-exposure.sh, which ensures that no service accidentally exposes ports to the public internet.
- Iterates through all 9 combinations of hardware (CPU, NVIDIA, AMD) and access profiles.
- Parses
docker compose configas JSON. - Validates that only the public Caddy service binds to interfaces other than
127.0.0.1. - Ensures memory-api mounts the vault as read-only.
Sources: scripts/check-exposure.sh:42-88
Summary
The Nyansa network design prioritizes isolation. By default, all AI and database services are trapped within a private Docker network. Users must explicitly choose an Access Profile—either the Public profile with Caddy-managed HTTPS or the Tailscale profile for private WireGuard-based access—to interact with the services. This layered approach ensures that internal components like Ollama and Qdrant remain inaccessible from the public internet.