chaib/atlas-os
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

wiki: merge clean grounded pages, fix malformed names, add App-Catalog/Fleet/Remote-Desktop + nav sidebar

Chaib Aarab 2026-06-22 21:58:12 +02:00
parent 2bd8ca941d
commit 43da932a67
13 changed files with 986 additions and 360 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
AI-Stack.-.md

@ -1,69 +0,0 @@
# AI Stack
Atlas OS routes every AI task by cost and complexity. The rule: **never burn paid tokens on work a free or local model can handle.** Free tier first, escalate only when it can't cope.
## Tier 0 — Zero-cost local (`localhost:8888/v1`, RTX A2000)
An OpenAI-compatible router exposes local Ollama models. Used for all non-critical subagent work, copy, summaries, translations, and classification.
| Alias | Backing | Use for |
|-------|---------|---------|
| `atlas-fast` | LLaMA 1B | Ultra-fast classification, routing, labels |
| `atlas-free` | Hermes3 | Dutch copy, summaries, FAQ, product descriptions |
| `atlas-code` | Qwen Coder | Code completion, simple fixes, boilerplate |
| `atlas-qwen` | qwen2.5 | General Dutch content, emails |
| `atlas-phi3` | qwen2.5:7b | Reasoning, analysis, comparisons |
| `atlas-auto` | smart router | Auto-picks the best free local model |
```python
import openai
client = openai.OpenAI(base_url="http://localhost:8888/v1", api_key="atlas")
client.chat.completions.create(model="atlas-auto", messages=[{"role":"user","content":"..."}])
```
## Tier 1 — Free cloud APIs
| Provider | Models | Best for |
|----------|--------|----------|
| Groq | llama-3.3-70b-versatile, mixtral-8x7b | Fast 70B reasoning, bulk tasks |
| Cerebras | llama-3.1-70b | Fastest inference, free tier |
| OpenRouter | 50+ free models incl. Gemini | Multi-model fallback |
| Gemini (via OpenRouter) | gemini-2.5-pro / 3.5-flash | 1M context, vision, PDF |
## Tier 2 — Paid Anthropic (only when free tiers can't cope)
| Task | Model |
|------|-------|
| Simple classification, short copy | `claude-haiku-4-5` |
| Code, multi-step reasoning, planning | `claude-sonnet-4-6` |
| Deep research, architecture, complex builds | `claude-opus-4-8` |
## Routing decision tree
```
copy / text / translation / summary / Dutch content
→ atlas-free (local) or Groq llama-3.3-70b (free cloud)
simple code / boilerplate / fix
→ atlas-code (local) or Cerebras (free cloud)
non-critical workflow subagent
→ atlas-auto or Groq (never Claude)
multi-step code / planning / complex reasoning
→ claude-sonnet-4-6
deep architecture / research / competitive analysis
→ claude-opus-4-8 or gemini-2.5-pro (free)
1M context / vision / PDF
→ Gemini via OpenRouter
```
## Always-on AI services
| Service | What it does |
|---------|-------------|
| `atlas-brain` | Collects mail + CRM + bank every 15 min → synthesizes the daily brief |
| `atlas-loop` | Background signal loop — publishes nudges to NATS |
| `atlas-meridian` | Autonomous decision engine / battle responder |
| `atlas-litellm` | Unified LLM proxy (OpenAI-compat API for all models above) |
| NATS mesh | Real-time event bus across all devices on the tailnet |
| Langfuse | Full LLM observability — every call traced with latency, cost, tokens |
All model calls flow through the LiteLLM proxy so cost and latency are traced centrally in Langfuse, regardless of which tier served the request.

104
AI-Stack.md Normal file

@ -0,0 +1,104 @@
# AI Stack
The AI layer is the reasoning core of Atlas OS: a durable decision spine, an autonomous-but-gated execution Brain, and a cost-tiered model router that always reaches for the cheapest capable model first. This page covers how those pieces fit together and where the rough edges still are.
For where these services surface in the desktop, see [[Atlas-OS]]. For hosting and isolation, see [[Infrastructure]] and [[Security]].
---
## At a glance
| Component | What it is | Where it lives |
|---|---|---|
| Kernel spine | `kernel.sqlite` — the durable record of decisions and events | Local SQLite spine |
| Atlas Brain | Reviewed-execution autonomous core | Reasoning layer over the spine |
| Policy gate | Human-approval checkpoint for sensitive actions | In front of every Brain action |
| LLM router | Cost-tiered model selector | `localhost:8888` |
| Headroom proxy | Context compression layer | In front of model calls |
Surfaced in Atlas OS under the **AI** category: Atlas Chat (Open WebUI), AI Gateway, Mindmap, and Leeragent.
---
## The spine — `kernel.sqlite`
Everything the Brain does is anchored to a single durable record. `kernel.sqlite` holds roughly **458 decisions** and **3,415 events**, giving the system an auditable memory of what was decided, when, and what happened around it.
The spine is the source of truth: decisions are recorded as first-class objects, and events accumulate as an append-style log around them. This is what lets autonomous execution stay reviewable — there is always a record to inspect rather than an opaque chain of model calls.
---
## The Brain — reviewed execution
**Atlas Brain** is the autonomous core, built on a *reviewed-execution* model. It can reason, plan, and act against the spine, but it is not unconditionally free to do so.
A **policy gate** sits in front of every action. It **always requires human approval** for three classes of action:
- **Money** — anything financial.
- **External communications** — anything that leaves the system to a third party.
- **Self-modification** — anything that changes Atlas itself.
Actions outside those classes can proceed under reviewed execution; the three gated classes never auto-execute. This is a hard rule, not a tunable setting — the gate is the safety boundary that makes autonomy acceptable.
---
## The router — cost-tiered model selection
The LLM router at **`localhost:8888`** picks the cheapest model that can handle a task, and only escalates when it must. The ordering is deliberate: local models cost nothing and stay private, free cloud tiers cost nothing but leave the box, and paid Claude is the last resort.
| Tier | Models | Cost profile |
|---|---|---|
| **1 — Local** | LLaMA 1B, hermes3, Qwen Coder, Qwen 7B | Zero cost, fully on-box |
| **2 — Free cloud** | Groq `llama-3.3-70b`, Cerebras, OpenRouter | Zero cost, off-box |
| **3 — Paid** | Claude | Used last, only when needed |
The principle: never burn paid tokens on work a free or local model can do. Classification, routing, copy, and summaries stay local; harder reasoning escalates only as far as it has to.
---
## Headroom — context compression
The **Headroom proxy** sits in front of model calls and compresses context before it reaches the model. This keeps prompts within working limits and reduces the cost and latency of each call — which in turn makes the cheaper tiers viable for more tasks than they otherwise would be.
---
## How a request flows
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart TD
REQ[Incoming task] --> BRAIN[Atlas Brain<br/>reviewed execution]
BRAIN --> SPINE[(kernel.sqlite<br/>decisions + events)]
BRAIN --> GATE{Policy gate}
GATE -->|money / external-comms / self-modify| HUMAN[Human approval required]
GATE -->|everything else| HEADROOM[Headroom proxy<br/>context compression]
HUMAN -->|approved| HEADROOM
HEADROOM --> ROUTER{LLM router<br/>localhost:8888}
ROUTER -->|cheapest capable| LOCAL[Local models<br/>LLaMA 1B / hermes3 / Qwen]
ROUTER -->|escalate| FREE[Free cloud<br/>Groq / Cerebras / OpenRouter]
ROUTER -->|last resort| CLAUDE[Claude paid]
LOCAL --> SPINE
FREE --> SPINE
CLAUDE --> SPINE
```
The Brain records its reasoning to the spine, passes through the policy gate, and — once cleared — compresses context via Headroom before the router selects a model from the cheapest capable tier. Results flow back into the spine.
---
## Known gap — cross-device chat history
Chat-history consolidation across devices is **not yet solved**. Conversation history is not currently unified into a single cross-device view, and reconciling it is a pending follow-up rather than a shipped feature. Treat per-device history as authoritative on its own device until this is addressed.
---
## Related pages
- [[Atlas-OS]] — the desktop where AI apps surface
- [[Infrastructure]] — hosting, Caddy, containers
- [[Security]] — EU-sovereign hosting, secrets, MFA
- [[Fleet-and-Mesh]] — NATS mesh and node-to-node messaging

75
Academy.md

@ -1,40 +1,67 @@
# Atlas Academy
The education arm of Atlas Corporation, running on the same box: [atlasacademy.nl](https://atlasacademy.nl). Coaching, courses, and a curriculum spanning ESF-funded tracks, BiSL, startup, and AI.
**Atlas Academy** ([atlasacademy.nl](https://atlasacademy.nl)) is the learning and coaching arm of the Atlas estate. It runs structured training tracks, one-on-one coaching, and a course catalog, and feeds every inbound learner straight into the [[Odoo]] CRM through an automated lead relay.
## Hosting
Like every other surface in the estate, the Academy is not a standalone silo: it lives under the **one-identity** model and is surfaced as a desktop app inside [[Atlas-OS]] under the **Sites** category.
Served as static HTML + a PHP product feed via nginx (TransIP subsite), fronted by the same brand and analytics as the rest of the stack.
---
**Key pages:** `index`, `coaching`, `cursussen`, `pricing`, `leerpad`, `shop`, `esf`, `bisl`, plus per-course pages (`cursussen/bisl`, `cursussen/startup`, `cursussen/ai`).
## Mission
## Lead capture → Odoo CRM
Atlas Academy exists to turn knowledge into employability and entrepreneurship. It packages practical IT, methodology, and AI skills into clear tracks — some of them ESF-funded — so learners can move from "interested" to "trained" to "placed in the [[Odoo]] CRM as a tracked lead" without friction.
Academy leads flow straight into the operator's Odoo CRM as `crm.lead` records — no manual re-entry.
---
```
Academy page (form)
│ POST { name, email, interest, source }
▼
atlas-academy-relay (systemd on atlas-01, port 7793)
│
├─► Odoo → creates crm.lead, returns { ok: true, lead_id: N }
└─► email fallback → info@atlascorporation.nl
## Tracks
The Academy is organised around four primary tracks plus coaching.
| Track | What it covers |
|---|---|
| **BiSL** | Business information services methodology — process and governance training. |
| **Startup** | Founder-focused track for getting a venture off the ground. |
| **AI** | Applied AI skills, aligned with the wider Atlas AI stack. |
| **ESF** | ESF-funded learning paths (European Social Fund) for eligible learners. |
| **Coaching** | One-on-one guidance alongside the structured tracks. |
A full **course catalog** sits on top of these tracks, browsable directly on the site.
---
## How a lead flows in
Every interested learner is captured on the Academy site and relayed into the [[Odoo]] CRM as a CRM lead. The relay is the single source of truth — no learner is tracked outside of it.
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart LR
V["Visitor<br/>atlasacademy.nl"] --> F["Track / course<br/>signup form"]
F --> R["Lead relay"]
R --> O["Odoo 19<br/>CRM lead"]
O --> P["Pipeline<br/>(Cockpit)"]
```
The relay is exposed via Caddy at `/academy-lead` (proxied to `127.0.0.1:7793`). It caches the Odoo UID so it doesn't re-authenticate on every lead.
The CRM record then surfaces in the **Pipeline** app under the [[Atlas-OS]] Cockpit category, so Academy leads are managed in the same place as every other commercial conversation across the estate.
## Product feed
---
Courses and hardware bundles are pulled from WooCommerce via a JSON feed, so the Academy shop stays in sync with the live store without duplicating product data.
## Where it sits in the estate
```
GET https://www.atlasworks.nl/academy-feed.php
→ { ts, count, products[] } # each: { id, title, price, type, img, url, cats }
```
| Aspect | Detail |
|---|---|
| Public site | [atlasacademy.nl](https://atlasacademy.nl) |
| Desktop app | Listed under **Sites** in [[Atlas-OS]] |
| CRM backend | [[Odoo]] 19 (lead relay) |
| Identity | Single estate identity, fronted by [[Authentik]] SSO where access is gated |
| Hosting | EU-sovereign single-VPS estate (see [[Infrastructure]]) |
Product types: `laptop`, `desktop`, `monitor`, `accessory`, `bundle`, `pos`.
---
## Principle
## Related pages
Academy content follows the same hard rule as the rest of Atlas OS: **no fabricated data.** No invented student counts, testimonials, ratings, or review quotes — sections are left as placeholders or omitted until real data exists.
- [[Atlas-OS]] — the browser desktop that surfaces the Academy as an app
- [[Odoo]] — CRM that receives Academy leads
- [[Authentik]] — single sign-on identity layer for the estate
- [[AI-Stack]] — the AI capability that the AI track aligns with
- [[Infrastructure]] — the EU-sovereign hosting the Academy runs on
- [[Home]] — wiki index

150
App-Catalog.md Normal file

@ -0,0 +1,150 @@
# App Catalog
The complete index of the **39 apps** inside [[Atlas-OS]] — the browser desktop served at `command.atlascorporation.nl/os/`. Apps are grouped into 7 categories. Every app runs on a single EU-sovereign Hetzner VPS (NL/DE, no US Cloud Act exposure), fronted by [[Caddy]] for TLS and gated by [[Authentik]] SSO (`forward_auth` via the embedded outpost). Admin identity: `atlasshb`.
> See also: [[Architecture]] · [[Security]] · [[AI-Stack]] · [[Fleet-and-Mesh]]
---
## Categories at a glance
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart TD
OS["Atlas OS desktop<br/>command.atlascorporation.nl/os/<br/>39 apps"]
OS --> C1["Cockpit"]
OS --> C2["Identity"]
OS --> C3["AI"]
OS --> C4["Work"]
OS --> C5["Files & Comms"]
OS --> C6["Ops"]
OS --> C7["Sites"]
```
| Category | What it covers |
|---|---|
| [Cockpit](#cockpit) | Daily command surfaces — money, inbox, pipeline, fleet, control |
| [Identity](#identity) | Single sign-on and secrets |
| [AI](#ai) | Chat, model routing, knowledge, learning |
| [Work](#work) | ERP, finance, documents, office, calendar |
| [Files & Comms](#files--comms) | Storage, mail, messaging |
| [Ops](#ops) | Git, automation, monitoring, remote access, infra |
| [Sites](#sites) | Public websites and the hub |
Access legend: 🔐 = behind Authentik SSO · 🔒 = Tailscale-private (`tailscale serve`, never public) · 🌐 = public site.
---
## Cockpit
The operator's day-to-day control surfaces — the first screens you reach for.
| App | What it does | Access |
|---|---|---|
| Today | Daily overview / start-of-day surface | 🔐 |
| Money | Finance snapshot and cash position | 🔐 |
| Inbox | Consolidated incoming items | 🔐 |
| Pipeline | Sales / deal pipeline view | 🔐 |
| Fleet | Device and POS fleet status | 🔐 |
| Control | Operator control panel | 🔐 |
---
## Identity
| App | What it does | Access |
|---|---|---|
| Authentik | Identity provider and SSO; the `forward_auth` gate in front of nearly every service | 🔐 |
| Vaultwarden | Password and secrets vault | 🔐 |
See [[Security]] for how Authentik fronts the stack and where secrets live.
---
## AI
| App | What it does | Access |
|---|---|---|
| **Atlas Chat** | Open WebUI front-end — the main chat surface into the [[AI-Stack]] | 🔐 |
| AI Gateway | Entry point / routing into the model layer | 🔐 |
| Mindmap | Visual idea and knowledge mapping | 🔐 |
| Leeragent | Learning / study agent | 🔐 |
> **Note — Atlas Chat.** Atlas Chat is **Open WebUI**. It talks to the LLM router at `localhost:8888`, which always picks the cheapest capable model first: local models (LLaMA 1B, hermes3, Qwen Coder, Qwen 7B) → free cloud (Groq llama-3.3-70b, Cerebras, OpenRouter) → paid Claude only as a last resort. A Headroom proxy compresses context to keep token use down. Full detail in [[AI-Stack]].
---
## Work
| App | What it does | Access |
|---|---|---|
| Odoo 19 | ERP / CRM — leads from [[Academy]] are relayed here | 🔐 |
| CFO | Finance / executive financial view | 🔐 |
| Bank (Firefly III) | Personal-finance / bank ledger manager | 🔐 |
| Paperless-ngx | Document archive with OCR and indexing | 🔐 |
| Office | Office / document suite | 🔐 |
| Calendar | Scheduling and calendar | 🔐 |
---
## Files & Comms
| App | What it does | Access |
|---|---|---|
| Nextcloud 31 | File storage, sync and sharing | 🔐 |
| Mail Admin (Stalwart) | Mail server administration (Stalwart) | 🔐 |
| Relay | Messaging / relay service | 🔐 |
---
## Ops
Engineering and infrastructure tooling — including remote access into the [[Fleet-and-Mesh]].
| App | What it does | Access |
|---|---|---|
| Forgejo | Self-hosted Git (code and this wiki) | 🔐 |
| n8n | Workflow automation | 🔐 |
| Uptime Kuma | Service uptime monitoring | 🔐 |
| MeshCentral | Remote-manage client POS devices and endpoints | 🔐 |
| Command | Command / control dashboard | 🔐 |
| **Remote Desktop** | Full Linux desktop in the browser — see note below | 🔐 |
| Architecture | Live architecture / topology view | 🔐 |
> **Note — Remote Desktop.** Remote Desktop is a **Webtop** instance running `ubuntu-xfce` over Selkies/WebRTC, served at `desktop.atlascorporation.nl` behind [[Authentik]] SSO. It ships with **Claude Code** and **Chromium** pre-installed. Because it is a *real* browser, Claude OAuth login works inside it — making this the standard place to drive agentic sessions from any device.
---
## Sites
Public-facing websites and the internal hub. These are the externally reachable web properties surfaced as desktop apps.
| App | What it does | Access |
|---|---|---|
| AtlasWorks | AtlasWorks site | 🌐 |
| Atlas Corp | Atlas Corporation corporate site | 🌐 |
| Agency | Atlas Agency site | 🌐 |
| Academy | atlasacademy.nl — BiSL / startup / AI / ESF tracks, coaching, course catalog; leads relayed into Odoo CRM | 🌐 |
| AtlasPOS | AtlasPOS site | 🌐 |
| Hub + client sites | Internal hub plus hosted client websites | 🌐 / 🔐 |
See [[Academy]] for the learning-platform detail.
---
## How access works
Almost every app sits behind one TLS edge and one identity gate:
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart LR
U["Browser"] --> CADDY["Caddy<br/>TLS edge"]
CADDY --> AUTH["Authentik<br/>forward_auth (SSO)"]
AUTH --> APPS["Atlas OS apps"]
TS["Tailscale spine<br/>(tailscale serve)"] -. private-only .-> APPS
```
- **Public services** terminate at Caddy and are protected by Authentik SSO.
- **Private services** are exposed only over the Tailscale spine via `tailscale serve` — never published to the public internet.
- See [[Architecture]] for the full ~55-container, ~24-public-service layout and [[Fleet-and-Mesh]] for MeshCentral, Tailscale and the NATS mesh.

263
Architecture.md

@ -1,186 +1,143 @@
# Atlas OS — System Architecture
# Architecture
## Overview: The One-Box Philosophy
Atlas OS runs on **one box**. Not a cluster, not a hyperscaler region, not a sprawl of managed services — a single EU-sovereign Hetzner VPS (NL/DE) that hosts the entire stack. This page explains why that is a deliberate design choice, how the edge funnels every request through one identity gate, and how internal services stay invisible to the public internet.
Atlas OS is deliberately a single-server architecture. One Hetzner CPX32 VPS
(8 vCPU · 16 GB RAM · 150 GB NVMe · Nuremberg) runs the complete operational
infrastructure of Atlas Corporation: CRM, finance, communications, AI, document
management, fleet control, and 11 websites.
**Why one box?** For a solo founder, operational simplicity outweighs redundancy.
One server = one bill, one SSH target, one Caddy config, one Authentik instance,
and zero inter-datacenter latency. The Tailscale overlay provides device-level
redundancy for access even if Caddy is down.
> EU-sovereign by design: hosting sits in NL/DE, outside the reach of the US Cloud Act.
---
## Network Topology
## The one-box philosophy
```
┌──────────────────────────────────────────────┐
Public Internet │ atlas-01 (Hetzner CPX32) │
───────────── │ ┌─────────┐ ┌──────────┐ │
Browser/App ──────►│ │ Caddy │───►│Authentik │──► Services │
│ │ (TLS) │ │ (SSO) │ │
│ └─────────┘ └──────────┘ │
│ │
Tailscale mesh │ ┌────────────────────────────────────────┐ │
──────────────── │ │ Private tailnet (100.x.x.x) │ │
iOS / PC / Laptop─►│ │ Webtop desktop · internal dashboards │ │
│ └────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
```
Everything Atlas needs to operate as a business lives on a single host:
### Public → SSO path (every service except mail ports)
1. Request hits Caddy (443 → Docker port)
2. Caddy runs `forward_auth` against Authentik outpost
3. Authentik validates session cookie / issues redirect to login
4. On success: Caddy copies `X-Authentik-*` headers and proxies to service
- **~55 Docker containers** running the full application estate
- **~24 public services** exposed to the internet
- **One Caddy edge** terminating TLS and routing every hostname
- **One identity provider** (Authentik) gating access before any app is reached
### Tailscale-only services
- Webtop remote desktop (`tailscale serve :8497`)
- Internal dashboards (portal, status feeds)
- atlas-01 SSH (blocked on public firewall, tailnet-only)
The advantage is operational gravity: one place to back up, one place to patch, one network namespace to reason about, one TLS configuration, one SSO policy. A solo operator can hold the whole system in their head. The trade-off — a single failure domain — is mitigated by nightly backups and the discipline of keeping the surface small.
| Layer | Component | Role |
|---|---|---|
| Edge | Caddy | TLS termination, reverse proxy, `forward_auth` to SSO |
| Identity | Authentik (embedded outpost) | SSO gate in front of protected apps |
| Apps | ~55 Docker containers | Cockpit, Work, AI, Files & Comms, Ops, Sites |
| Private spine | Tailscale | Internal-only reach via `tailscale serve` |
| Mesh | NATS | Node-to-node messaging |
| Remote | MeshCentral | Manage client POS / devices |
Admin identity across the box: **atlasshb**.
---
## Service Layers
## Request path: Caddy edge → Authentik SSO → apps
### Tier 0 — Identity & Security
- **Authentik** (`auth.atlascorporation.nl`) — OIDC/SSO, MFA, app proxies
- **Vaultwarden** (`vault.atlascorporation.nl`) — end-to-end encrypted password vault
- **Caddy** — automatic TLS, reverse proxy, the sole public entry point
Every public hostname resolves to Caddy. Caddy terminates TLS, then — for protected routes — performs a `forward_auth` handshake against the **embedded Authentik outpost**. Only after Authentik confirms the session does the request reach the upstream container.
### Tier 1 — Core Business
- **Odoo 19** — CRM, invoicing, project management, contacts
- **Nextcloud 31** — file storage, DAV (calendar/contacts sync to iOS)
- **Stalwart** — self-hosted email: SMTP, IMAPS, JMAP, Sieve
- **Forgejo** — self-hosted git (this very repo)
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart TD
U[Browser / client] -->|HTTPS| C[Caddy edge<br/>TLS termination]
C -->|forward_auth| A[Authentik<br/>embedded outpost]
A -->|session valid| C
A -.->|no session| L[Login / MFA]
L --> A
C -->|authed request| OS[Atlas OS desktop<br/>command.atlascorporation.nl/os/]
C --> APPS[Protected apps]
### Tier 2 — Finance & Operations
- **Firefly III** — double-entry bookkeeping, budgets, reconciliation
- **Enable Banking** — PSD2 bank feed (ING, Knab → Firefly)
- **Paperless-ngx** — document management, OCR, auto-tagging
- **n8n** — workflow automation (webhooks, scheduled tasks)
- **Uptime Kuma** — service health monitoring with alerting
subgraph box["One Hetzner VPS — EU-sovereign · ~55 containers"]
C
A
OS
APPS
subgraph internal["Internal-only (no public ingress)"]
T[Loopback-bound services]
TS[tailscale serve]
end
APPS --- T
T --- TS
end
### Tier 3 — AI & Intelligence
- **LiteLLM proxy** — unified OpenAI-compat API to all models (local + cloud)
- **Open-WebUI** — ChatGPT-style UI on top of LiteLLM
- **Atlas Brain** (`atlas_brain.py`) — Python signal collector, runs every 15 min
- **Atlas Loop** — background nudge cycle, publishes to NATS
- **Atlas Meridian** — autonomous decision engine / battle responder
- **Langfuse** — LLM observability: every call traced with latency, cost, tokens
- **Local model router** (`:8888`) — OpenAI-compat router for local Ollama models
TS -.->|private spine| TN[Tailscale tailnet]
APPS --> M[(The Mind<br/>kernel.sqlite spine)]
M --> R[LLM router :8888]
```
### Tier 4 — Fleet & Infrastructure
- **MeshCentral** — remote device access, POS terminal fleet management
- **NATS** — real-time pub/sub event bus across all Tailscale devices
- **Atlas heartbeat sink** — aggregates device heartbeats from the NATS mesh
- **Atlas cockpit feeds** — on-disk JSON feeds consumed by the OS desktop
- **Webtop** — full XFCE Linux desktop in the browser (tailnet-only)
### Tier 5 — Managed Sites (11 sites)
All served via Caddy. WordPress sites run in isolated Docker stacks:
| Domain | Stack | Notes |
|--------|-------|-------|
| `atlasworks.nl` | Docker: works-wordpress | Live WooCommerce (Caddy :8111) |
| `atlascorporation.nl` | Docker: corp-wordpress | Corporate site |
| `atlasagency.nl` | Docker: agency-wordpress | Agency services |
| `atlasacademy.nl` | TransIP nginx (static HTML) | Academy landing |
| `atlaspos.nl` | TransIP | AtlasPOS product site |
| `atlashub.nl` | Docker: atlashub | Hub platform |
| `bicosagency.nl` | Docker: bicos-wordpress | Client site |
| `budgetenergiecoach.nl` | Docker | Client site |
| `hkintercare.nl` | Docker: hkincare-wordpress | Client site |
| `jouwenergieadvies.nl` | Docker | Client site |
| `reclamemans.nl` | Docker | Client site |
The browser desktop at **command.atlascorporation.nl/os/** is itself one of these protected apps — 39 apps organised into Cockpit, Identity, AI, Work, Files & Comms, Ops, and Sites categories. See [[Atlas-OS]] for the full app catalog and [[Security]] for the SSO and MFA model.
---
## Data Flow — Atlas Brain Cycle
## Loopback-binding + `tailscale serve` for internal services
```
Every 15 minutes (atlas-brain.service):
┌──────────────────────────────────────────┐
│ Signal collection phase │
│ ├── 7 IMAP mailboxes (read-only) │
│ ├── Odoo REST API (leads, contacts) │
│ ├── Enable Banking (bank transactions) │
│ └── atlas-01 health/fleet feeds │
└──────────────────┬───────────────────────┘
│
▼
atlas-state.json
│
▼
LLM synthesis (model router):
atlas-auto (local) → Groq 70B → Claude Opus
│
▼
atlas-brief-spoken.json (daily brief)
│
▼
Atlas OS cockpit panels (Today · Money · Inbox · Pipeline)
```
Not everything should be reachable from the public internet. Atlas keeps its internal surface small with two complementary techniques:
### 1. Loopback binding
Internal-only services bind to **loopback** rather than a public interface. They are reachable from the box itself (and from other containers/proxies on the host) but have **no public ingress**. Caddy can still reverse-proxy to them when an authenticated, SSO-gated route legitimately needs them — but the open internet cannot hit them directly.
### 2. `tailscale serve` over the private spine
Where a service needs to be reached from another machine — but should never be public — it is exposed via **`tailscale serve`** on the Tailscale tailnet. This is the private spine: only devices enrolled in the tailnet can reach those services. The rule is explicit and absolute:
> Internal services are reached via `tailscale serve` — **never** exposed publicly.
This is why the public service count (~24) is far smaller than the container count (~55): the majority of containers are either dependencies of other services or deliberately kept off the public edge, reachable only over loopback or the tailnet.
| Exposure tier | How it's reached | Example surface |
|---|---|---|
| Public | Caddy → Authentik → app | Atlas OS desktop, public sites |
| Loopback | Bound to localhost; proxied via authed Caddy route only | Backend dependencies |
| Tailnet | `tailscale serve`, tailnet members only | Internal-only services |
The **Remote Desktop** (Webtop `ubuntu-xfce`, Selkies/WebRTC) at `desktop.atlascorporation.nl` is a good illustration of the edge model in practice: it sits behind Authentik SSO, and ships with Claude Code + Chromium pre-installed so OAuth logins work in a real browser. See [[Remote-Desktop]].
---
## The AI Mesh
## Data flows through the Mind
Atlas is not just a pile of apps behind a proxy — it has a reasoning core, and operational data flows through it.
- **The spine is `kernel.sqlite`** — the canonical store of decisions and events (~458 decisions, ~3415 events recorded).
- **Atlas Brain** is the reviewed-execution autonomous core. It can act, but it acts under a gate.
- **The policy gate ALWAYS requires human approval** for anything touching **money**, **external communications**, or **self-modification**. There is no autonomous path around it.
- **The LLM router at `localhost:8888`** picks the cheapest capable model for each task, escalating only when needed:
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart LR
Q[Task] --> R{LLM router<br/>localhost:8888}
R -->|first| LOC[Local models<br/>LLaMA 1B · hermes3 · Qwen Coder · Qwen 7B]
R -->|then| FREE[Free cloud<br/>Groq llama-3.3-70b · Cerebras · OpenRouter]
R -->|last| PAID[Claude — paid]
LOC --> H[Headroom proxy<br/>context compression]
FREE --> H
PAID --> H
```
atlas-01 (NATS JetStream server)
│
├── subjects:
│ atlas.events.* system events (disk, CPU, service state)
│ atlas.heartbeat.* device health pings
│ atlas.jobs.* delegated compute jobs (Ollama on NEBULA)
│ atlas.brief.* daily brief push to all devices
│
└── subscribers:
Caddy PC (this machine) ← atlas-events-collector
NEBULA (HP EliteBook) ← atlas-delegate-worker (5 Ollama models)
MET-Desktop ← Odoo failover + fleet monitor
```
The router binds locally (`localhost:8888`) — itself an example of the loopback-binding principle: the model router is an internal service, not a public endpoint. The **Headroom proxy** compresses context so requests stay cheap. Local models are tried first, free cloud tiers next, and Claude (paid) only as a last resort.
For how the Mind, the policy gate, and the router fit together operationally, see [[AI-Stack]] and [[Atlas-Brain]].
---
## Caddy SSO Pattern
## Why this holds together
Every SSO-gated service uses this Caddyfile block (see `deploy/caddy/Caddyfile.template`):
```caddy
app.example.com {
# Authentik outpost endpoints (must come first)
reverse_proxy /outpost.goauthentik.io/* authentik-server:9000
# SSO gate — redirects to login if no valid session
forward_auth authentik-server:9000 {
uri /outpost.goauthentik.io/auth/caddy
copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email
X-Authentik-Name X-Authentik-Uid X-Authentik-Jwt
}
# Only reached after successful authentication
reverse_proxy localhost:APP_PORT
}
```
| Principle | Implementation |
|---|---|
| One failure domain, one control plane | Single Hetzner VPS, ~55 containers |
| Sovereign data | EU hosting (NL/DE), no US Cloud Act exposure |
| One front door | Caddy terminates TLS for every hostname |
| One identity gate | Authentik `forward_auth` on the embedded outpost |
| Small public surface | Loopback binding + `tailscale serve` keep internals private |
| Cheapest-capable compute | LLM router: local → free cloud → Claude last |
| No silent autonomy on what matters | Policy gate requires human approval for money / comms / self-modify |
---
## Docker Compose Topology
### See also
| Stack | File | Services |
|-------|------|----------|
| Core | `deploy/compose/atlas-core.yml` | Authentik, Nextcloud, Stalwart, Forgejo, Vaultwarden |
| AI | `deploy/compose/atlas-ai.yml` | LiteLLM, Open-WebUI, Langfuse |
| Business | `atlas-odoo.yml` | Odoo 19 + PostgreSQL |
| Finance | `atlas-finance.yml` | Firefly III + Paperless-ngx + Enable Banking |
| Fleet | `atlas-fleet.yml` | MeshCentral + NATS + Uptime Kuma |
| Sites | Per-site compose | WordPress stacks |
| Desktop | `deploy/webtop-docker-compose.yml` | Webtop (tailnet-only) |
All stacks share the `atlas-net` Docker network. Caddy is the **sole** process with
public port bindings (80/443). All internal services bind only to `127.0.0.1:PORT`.
- [[Atlas-OS]] — the 39-app browser desktop
- [[AI-Stack]] — the Mind, the router, and the policy gate
- [[Security]] — EU-sovereign hosting, MFA, backups, secrets
- [[Fleet-and-Mesh]] — MeshCentral, Tailscale spine, NATS
- [[Remote-Desktop]] — Webtop behind SSO

189
Deploy.md

@ -1,32 +1,181 @@
# Deploy
One-command installer for Atlas OS on a fresh Debian 12 / Ubuntu 24.04 server.
This page walks through standing up **your own** Atlas OS instance: clone the repo, run the installer, point your domain at it, and let Caddy + Authentik gate every service. The end state is a browser desktop at `command.<your-domain>/os/` with the full app catalog described in [[Atlas-OS]], all fronted by TLS and SSO.
> **Sovereignty note:** the reference deployment runs on a single Hetzner VPS in the EU (NL/DE), so there is no US Cloud Act exposure. Any EU-based VPS with Docker works equally well. See [[Security]] for the full posture.
---
## Prerequisites
- Debian 12 or Ubuntu 24.04 (x86_64)
- Root access
- A domain with DNS pointed at the server
- A Tailscale account (free tier works)
| Requirement | Detail |
|---|---|
| Host | A single Linux VPS with Docker + Docker Compose. The reference box runs ~55 containers / ~24 public services — size CPU/RAM/disk accordingly. |
| Domain | One domain you control, with the ability to add DNS records (wildcard recommended). |
| DNS | An `A`/`AAAA` record for the apex and a wildcard `*.<your-domain>` pointing at the VPS public IP. |
| Ports | `80` and `443` open to the world (Caddy handles ACME + TLS). Everything else stays private. |
| Admin identity | An email for the first Authentik admin account. The reference admin identity is `atlasshb` — pick your own. |
| Optional | A [Tailscale](https://tailscale.com) account if you want the private spine described in [[Fleet-and-Mesh]]. |
## Install
---
```bash
git clone https://git.atlascorporation.nl/chaib/atlas-os
cd atlas-os
chmod +x deploy/install.sh
sudo ./deploy/install.sh --domain yourdomain.com --email admin@yourdomain.com
## Deployment at a glance
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart TD
A[git clone the repo] --> B[deploy/install.sh]
B --> C[Bring your own domain<br/>edit .env]
C --> D[Caddy brings up TLS<br/>via ACME on 80/443]
D --> E[Authentik SSO<br/>forward_auth gate]
E --> F[atlas-core.yml<br/>compose stack up]
F --> G[Atlas OS desktop<br/>command.your-domain/os/]
```
## Post-install
---
1. Open `https://auth.yourdomain.com` and complete Authentik setup
2. Create your admin user in Authentik
3. Open `https://command.yourdomain.com/os/` — Atlas OS desktop boots
4. Add the AI stack: `docker compose -f deploy/compose/atlas-ai.yml up -d`
5. Configure `server/atlas_brain.py` with your mail accounts
## 1. Clone the repo
## Secrets
```bash
git clone <your-forgejo-url>/atlas/atlas-os.git
cd atlas-os
```
The installer generates strong secrets at `/opt/atlas/secrets/atlas.env` (chmod 600).
Never commit this file. It is in `.gitignore`.
The repo ships its own docs — read `README.md` and the `docs/` directory before changing defaults. The git host itself (Forgejo) is one of the Ops apps in [[Atlas-OS]], so once you are live you can self-host the source too.
---
## 2. Run the installer
The installer prepares the host (Docker checks, directory layout, secret scaffolding) and writes a starter environment file.
```bash
./deploy/install.sh
```
`install.sh` will:
1. Verify Docker / Compose are present.
2. Create the on-disk layout, including `/opt/atlas/secrets` (created `chmod 600`, never committed — see [[Security]]).
3. Generate a `.env` template for you to fill in (domain, admin email, secrets).
4. Pre-pull the base images referenced by `atlas-core.yml`.
> Secrets live in two places only: the Vaultwarden vault (an Identity app in the catalog) and `/opt/atlas/secrets` on disk. `.gitignore` enforces that none of them enter git.
---
## 3. Bring your own domain
Atlas OS is domain-agnostic. Set your domain once, in `.env`, and every service inherits it as a subdomain.
```bash
# .env
ATLAS_DOMAIN=your-domain.com
ATLAS_ADMIN_EMAIL=you@your-domain.com
```
Then add DNS records pointing at your VPS:
| Record | Name | Value |
|---|---|---|
| `A` | `@` | `<vps-ip>` |
| `A` | `*` | `<vps-ip>` |
The wildcard lets Caddy serve each app on its own hostname. Reference hostnames you will end up with:
| Hostname | Service |
|---|---|
| `command.<your-domain>/os/` | Atlas OS browser desktop ([[Atlas-OS]]) |
| `desktop.<your-domain>` | Webtop Remote Desktop ([[Remote-Desktop]]) |
| `atlasacademy.nl`-style site | Academy and your other [[Sites]] |
---
## 4. Caddy + Authentik gate
Caddy is the single public entry point. It terminates TLS (automatic ACME certificates on ports 80/443) and reverse-proxies to the internal containers. In front of protected apps it calls Authentik via `forward_auth` on the embedded outpost, so every request must carry a valid SSO session before it reaches the upstream.
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart LR
U[Browser] -->|HTTPS 443| C[Caddy<br/>TLS termination]
C -->|forward_auth| AK[Authentik<br/>embedded outpost]
AK -->|allow / deny| C
C -->|authenticated| S[Atlas OS apps<br/>~24 public services]
```
What this gives you:
- **TLS everywhere** — Caddy issues and renews certificates automatically.
- **One front door** — only `80`/`443` are public; container ports stay on the internal Docker network.
- **SSO on every app** — Authentik's `forward_auth` means a single login covers the whole desktop. The first admin you create during setup (reference: `atlasshb`) owns the directory.
- **Private-only services** — anything you do *not* want public is exposed over the Tailscale spine via `tailscale serve` instead of through Caddy. Details in [[Fleet-and-Mesh]].
After editing the Caddyfile, reload it:
```bash
caddy reload --config /etc/caddy/Caddyfile
```
---
## 5. The `atlas-core.yml` compose stack
`atlas-core.yml` is the heart of the deployment — the Compose file that brings up the core services (Caddy, Authentik, and the baseline app containers). Bring the stack up once your `.env` and DNS are in place:
```bash
docker compose -f atlas-core.yml up -d
```
Useful operations:
```bash
# Check what is running
docker compose -f atlas-core.yml ps
# Tail logs for a single service
docker compose -f atlas-core.yml logs -f caddy
# Pull updates and roll forward
git pull
docker compose -f atlas-core.yml pull
docker compose -f atlas-core.yml up -d
```
The full reference deployment runs ~55 containers and ~24 public services. `atlas-core.yml` defines the baseline; additional app modules layer on top of it. The complete catalog — Cockpit, Identity, AI, Work, Files & Comms, Ops, and Sites — is documented in [[Atlas-OS]], and the AI router / Brain layer in [[AI-Stack]].
---
## 6. First login & verification
1. Browse to `https://command.<your-domain>/os/`.
2. Caddy redirects you to Authentik for the first-run admin setup. Create your admin identity.
3. Land on the Atlas OS desktop. Confirm the app launcher loads.
4. Open **Uptime Kuma** (an Ops app) to confirm services report healthy.
If a service 502s, check the Caddy logs first (`docker compose -f atlas-core.yml logs caddy`) and confirm DNS + the wildcard record have propagated.
---
## Repo docs reference
For anything beyond this overview, the repo is the source of truth:
| File | Covers |
|---|---|
| `README.md` | Project overview and quick start |
| `deploy/install.sh` | The installer this page runs |
| `atlas-core.yml` | The core Compose stack |
| `docs/` | Per-service configuration and operations |
| `.env` (generated) | Your domain, admin email, and secret wiring |
---
## Related pages
- [[Atlas-OS]] — the desktop and the full 39-app catalog
- [[Architecture]] — how the single-VPS, Caddy-fronted design fits together
- [[Security]] — EU-sovereign hosting, MFA, secrets, backups
- [[Fleet-and-Mesh]] — Tailscale spine, NATS mesh, MeshCentral
- [[AI-Stack]] — kernel spine, Atlas Brain, LLM router
- [[Remote-Desktop]] — Webtop instance for browser-based dev

97
Fleet-and-Mesh.md Normal file

@ -0,0 +1,97 @@
# Fleet & Mesh
How Atlas reaches, manages, and messages every device and node in the estate — from a client POS terminal in a Tilburg venue back to the single Hetzner VPS that runs the platform.
Three layers cooperate:
| Layer | Tool | Role |
|---|---|---|
| **Device management** | MeshCentral | Remote-manage client POS terminals and devices |
| **Private spine** | Tailscale | Encrypted private network connecting nodes; internal services published via `tailscale serve` |
| **Node messaging** | NATS mesh | Node-to-node messaging between Atlas hosts |
All of this is fronted by the same EU-sovereign infrastructure described in [[Infrastructure]], and reachable through the browser desktop documented in [[Atlas-OS]].
---
## MeshCentral — device & POS management
MeshCentral is the remote-management plane for client devices, including the POS terminals that AtlasPOS deploys into venues. It lets the operator see, reach, and service a terminal without being physically present.
MeshCentral is exposed as an app in the **Ops** category of [[Atlas-OS]], so it opens directly from the browser desktop alongside Forgejo, n8n, Uptime Kuma, Command, and Remote Desktop.
**What it provides for a managed device:**
- Remote control and assistance for client POS terminals and other enrolled devices
- A central view of enrolled devices grouped under the operator identity
- A reach-back channel for support and maintenance
Like every other public-facing service, MeshCentral sits behind Caddy for TLS and is protected through the platform's SSO and access model — see [[Security]].
---
## Tailscale — the private spine
Tailscale is the **private network spine** that links Atlas nodes together. It is deliberately kept private:
> Internal services are published over the spine with `tailscale serve` — **never** exposed publicly.
This gives a clean split between what is public and what is private:
- **Public** services are fronted by Caddy with TLS and gated by Authentik SSO forward_auth (see [[Architecture]] and [[Security]]).
- **Private / internal** services ride the Tailscale spine and are reached over the tailnet via `tailscale serve`, with no public route.
The practical effect: administrative and internal tooling stays off the public internet entirely, while only the curated set of public services is reachable from outside.
---
## NATS mesh — node-to-node messaging
NATS provides **node-to-node messaging** across the Atlas mesh. Where Tailscale is the transport spine and MeshCentral is the device-management plane, NATS is the message bus that lets Atlas hosts talk to each other.
A full **round-trip** over the NATS mesh has been proven, confirming that nodes can publish and receive across the spine.
This messaging layer is what allows distributed Atlas components to coordinate without each one needing a direct, hand-wired connection to the others.
---
## How a client POS terminal is reached & managed
The diagram below shows the path from the operator, through the platform, out to a client POS terminal in a venue.
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart TB
OP["Operator (atlasshb)"]
OS["Atlas OS desktop<br/>command.atlascorporation.nl/os/"]
CADDY["Caddy (TLS)<br/>+ Authentik SSO"]
MC["MeshCentral<br/>device management"]
TS["Tailscale<br/>private spine"]
NATS["NATS mesh<br/>node messaging"]
POS["Client POS terminal<br/>(venue)"]
NODE["Atlas node"]
OP --> OS --> CADDY
CADDY --> MC
MC -->|remote manage| POS
CADDY -. internal via tailscale serve .-> TS
TS --- NODE
NODE -. NATS round-trip .-> NATS
NATS --- NODE
```
**Walkthrough:**
1. The operator (`atlasshb`) opens the browser desktop at `command.atlascorporation.nl/os/` and launches **MeshCentral** from the Ops category.
2. The request passes through **Caddy** (TLS) and the **Authentik** SSO gate — the same front door as every public service.
3. **MeshCentral** establishes the remote-management session with the enrolled **client POS terminal** in the venue.
4. Internal and node-level traffic stays on the **Tailscale** spine (published with `tailscale serve`, never public), and Atlas hosts coordinate over the **NATS mesh**.
---
## Where this fits
- [[Atlas-OS]] — the browser desktop where MeshCentral, Command, Uptime Kuma and other Ops apps live
- [[Infrastructure]] — the single Hetzner VPS, Caddy, and the container estate this all runs on
- [[Security]] — EU-sovereign hosting, SSO, MFA, and the public/private split
- [[Architecture]] — how the layers and services compose end to end

79
Home.md

@ -1,26 +1,63 @@
# Atlas OS Wiki
# Atlas OS
Your entire business on one hardened Linux server — one SSO identity, one browser login, one OS.
**One login. One sovereign machine. 39 apps in your browser.**
![Atlas OS](https://git.atlascorporation.nl/chaib/atlas-os/raw/branch/main/assets/header.svg)
Atlas OS is a browser-based desktop for running an entire company from a single, EU-sovereign server. No US Cloud Act exposure, no scattered SaaS logins — every tool lives behind one identity at **command.atlascorporation.nl/os/**, fronted by Caddy (TLS) with Authentik single sign-on.
## Browse
- **[Architecture](Architecture)** — the one-box design, network topology, SSO path
- **[Services](Services)** — full catalog of 55 containers and 39 apps
- **[AI-Stack](AI-Stack)** — local → free cloud → paid routing
- **[Deploy](Deploy)** — one-command install on a fresh server
- **[Academy](Academy)** — atlasacademy.nl + Odoo lead relay
- **[Islamic-Layer](Islamic-Layer)** — Adhan, Quran at logon, family-safe DNS
- **[Security](Security)** — the trust model
## The desktop
![Desktop](https://git.atlascorporation.nl/chaib/atlas-os/raw/branch/main/assets/desktop-preview.svg)
## Architecture at a glance
![Architecture](https://git.atlascorporation.nl/chaib/atlas-os/raw/branch/main/assets/architecture.svg)
It runs on **one Hetzner VPS** (NL/DE), hosting roughly **55 Docker containers** and **~24 public services**. Behind the desktop sits an autonomous AI core — the Atlas Brain — gated so that money, external comms, and self-modification always require a human to approve.
---
Repo: [chaib/atlas-os](https://git.atlascorporation.nl/chaib/atlas-os) · Built by Chaib Aarab · Atlas Corporation, Tilburg NL
## What it is
| | |
|---|---|
| **Access** | Browser desktop at `command.atlascorporation.nl/os/` |
| **Apps** | 39, grouped into Cockpit, Identity, AI, Work, Files & Comms, Ops, and Sites |
| **Identity** | Authentik SSO (forward_auth on the embedded outpost); admin: `atlasshb` |
| **Hosting** | Single Hetzner VPS, EU-sovereign (NL/DE) — no US Cloud Act reach |
| **Edge** | Caddy reverse proxy with automatic TLS |
| **Private spine** | Tailscale + NATS mesh; internal services never exposed publicly |
| **AI core** | Atlas Brain (reviewed-execution) on a `kernel.sqlite` decision spine |
---
## Map of the wiki
| Page | What's inside |
|---|---|
| [[Architecture]] | The single-VPS topology — Docker, Caddy, Authentik, how a request flows from browser to service |
| [[App-Catalog]] | All 39 apps by category, what each one is, and where it lives |
| [[AI-Stack]] | Atlas Brain, the `kernel.sqlite` spine, the policy gate, and the cheapest-model-first LLM router |
| [[Fleet-and-Mesh]] | MeshCentral device management, the Tailscale spine, and the NATS node-to-node mesh |
| [[Remote-Desktop]] | The Webtop XFCE desktop with Claude Code + Chromium, behind Authentik SSO |
| [[Academy]] | Atlas Academy — BiSL, startup, AI and ESF-funded tracks, coaching, and Odoo lead relay |
| [[Security]] | EU-sovereign hosting, MFA, nightly backups, and where secrets actually live |
| [[Deploy]] | How changes ship to the box |
---
## How it fits together
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart TD
U([Browser]) --> C[Caddy + TLS]
C --> A[Authentik SSO]
A --> OS[Atlas OS desktop<br/>39 apps]
OS --> AI[AI stack<br/>Brain + router]
OS --> WK[Work + Files<br/>Odoo, Firefly, Nextcloud]
OS --> OPS[Ops<br/>Forgejo, n8n, MeshCentral]
AI --> K[(kernel.sqlite)]
OPS -. private spine .-> MESH[Tailscale + NATS]
```
---
## Start here
- New to the system? Read [[Architecture]] first, then browse the [[App-Catalog]].
- Curious about the autonomous core and how cost is controlled? Go to [[AI-Stack]].
- Need to ship a change? See [[Deploy]].
> **Principle:** sovereign by default, approved by a human where it matters. EU hosting, one identity, and a policy gate that never lets the Brain move money or talk to the outside world on its own.

31
Islamic-Layer.-.md

@ -1,31 +0,0 @@
# Islamic Layer
A first-class part of Atlas OS — woven into the OS and the device fleet, not bolted on. Live since 2026-05-09.
## Components
| Layer | What it does |
|-------|-------------|
| Family-safe DNS | AdGuard Family + a hosts blocklist across the network |
| Content filtering | HaramBlur on browsers |
| Quran at logon | Recitation plays when the workstation logs in |
| Adhan + lock | At El Feth Tilburg salah times, the Adhan plays and the screen locks |
| Sunnah reminders | Recurring reminders surfaced across the device fleet |
## Salah timing
Prayer times track **El Feth Mosque, Tilburg**. At each salah time the fleet plays the Adhan and locks the active screen — a deliberate, enforced pause rather than a passive notification.
## Where it lives
All assets and scripts are under the Atlas artifacts tree:
```
Sync/atlas-artifacts/atlas-os/islamic/
```
This keeps the layer versioned and reproducible alongside the rest of the Atlas OS configuration, and syncs across devices through the same Syncthing topology as the other artifacts.
## Principle
The Islamic layer is treated as core infrastructure: it ships with the OS, runs on the fleet by default, and is documented and version-controlled like every other service.

12
Islamic-Layer.md Normal file

@ -0,0 +1,12 @@
# Atlas Islamic Layer
A personal-sovereignty layer for the operator — proof that *sovereign* means values, not just data residency.
| Element | What it does |
|---|---|
| **Adhan** | Plays at El Feth (Tilburg) salah times; screen locks at prayer |
| **Qur'an at logon** | Recitation on session start |
| **AdGuard Family DNS** | Network-level content filtering, plus HaramBlur on browsers |
| **Sunnah reminders** | Gentle prompts through the day |
Values-aligned by design, on the same one-identity Atlas estate. See [[Home]] · [[Security]].

101
Remote-Desktop.md Normal file

@ -0,0 +1,101 @@
# Remote Desktop
A full Linux desktop, running in your browser, behind single sign-on. Atlas OS ships a **Webtop (ubuntu-xfce)** instance so you can drive a real graphical environment — with **Claude Code** and **Chromium** pre-installed — from any device, without exposing the box to the public internet.
> Why it exists: some tools refuse to behave on a headless server. A real desktop with a real browser is the difference between "works" and "stuck on a login screen." This page covers the what, the why, and exactly how to open it and boot Claude.
---
## At a glance
| Property | Value |
|---|---|
| App name | Remote Desktop |
| Category | [[Ops]] |
| URL | `desktop.atlascorporation.nl` |
| Base image | Webtop, `ubuntu-xfce` flavour |
| Streaming | Selkies over WebRTC |
| Access control | [[Authentik]] SSO (Caddy `forward_auth`) |
| Pre-installed | Claude Code, Chromium |
| Hosting | Single EU-sovereign Hetzner VPS (NL/DE) |
---
## What it is
Webtop is a containerized desktop environment streamed to the browser. The Atlas instance runs the **XFCE** desktop on **Ubuntu**, rendered to your browser via **Selkies / WebRTC** — so it feels like a local machine, with mouse, keyboard, clipboard and windowed apps, but nothing is installed on your end. Any browser on any device that can reach the URL is enough.
It is one of the apps in the **Ops** category of [[Atlas-OS]], alongside [[Forgejo]] git, n8n, Uptime Kuma, MeshCentral, Command and the [[Architecture]] map.
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart LR
U["Your browser<br/>(any device)"] -->|HTTPS| C["Caddy<br/>TLS + forward_auth"]
C -->|auth check| A["Authentik SSO<br/>embedded outpost"]
A -->|allowed| C
C -->|WebRTC stream| W["Webtop<br/>ubuntu-xfce"]
subgraph desk["Inside the desktop"]
CC["Claude Code"]
CR["Chromium<br/>(real browser)"]
end
W --- desk
CR -->|OAuth login| ANT["Anthropic"]
```
---
## Why a real browser solves Claude OAuth on a server
Logging Claude Code into Anthropic uses an **OAuth flow** that wants to open a browser, complete a redirect, and hand the token back. On a bare headless server there is no browser to open and no graphical session to complete the redirect in — so the login stalls.
The Webtop desktop fixes this directly:
- It provides a **real, full desktop session** — not a headless shell.
- **Chromium is pre-installed** inside that session, so the OAuth redirect opens and completes like it would on a laptop.
- Claude Code runs in the same desktop, so the **token lands back in the right place** with no copy-paste gymnastics or tunneling tricks.
The result: you get the same smooth `claude` login you would have on a local machine, but the agent and its workspace live on the server — close to the rest of the Atlas stack.
---
## How to open it
1. From the [[Atlas-OS]] desktop, open the **Remote Desktop** app (Ops category), or go directly to `desktop.atlascorporation.nl`.
2. You will hit **[[Authentik]] SSO** first (enforced by Caddy `forward_auth`). Sign in with your Atlas identity. See [[Authentik]] and [[Security]] for MFA details.
3. Once authenticated, the **Webtop ubuntu-xfce** desktop streams into the browser over WebRTC. Use it like any desktop — taskbar, file manager, terminal, windows.
---
## How to boot Claude
Inside the desktop:
1. Open a **terminal** from the XFCE taskbar.
2. Run Claude Code:
```bash
claude
```
3. On first run it will start the **OAuth login**. **Chromium** opens automatically (or open it from the taskbar and paste the auth URL).
4. Complete the Anthropic sign-in in Chromium. Because this is a real browser in a real session, the redirect completes and the token is captured — no extra steps.
5. You are now in an authenticated Claude Code session, running server-side, next to the rest of the Atlas stack.
> Tip: keep the Chromium window open during the login redirect. The flow needs the browser to finish the handshake before the token is written.
---
## Security notes
- **SSO-gated.** Every request passes [[Authentik]] via Caddy `forward_auth` on the embedded outpost before the desktop loads. No anonymous access.
- **TLS everywhere.** Caddy terminates HTTPS for the public hostname.
- **EU-sovereign.** Like the rest of [[Atlas-OS]], it runs on a single Hetzner VPS in the NL/DE region.
- **Secrets discipline.** Anthropic credentials obtained through the in-desktop OAuth flow stay on the server. Long-lived secrets live in Vaultwarden / `/opt/atlas/secrets` (chmod 600), never in git. See [[Security]].
---
## Related pages
- [[Atlas-OS]] — the browser desktop and app catalog this lives in
- [[Authentik]] — the SSO gate in front of Remote Desktop
- [[Security]] — EU-sovereign hosting, MFA, secrets policy
- [[AI-Stack]] — the LLM router and Atlas Brain that Claude Code works alongside
- [[Architecture]] — the full container and service map

155
Security.md

@ -1,46 +1,135 @@
# Security model
# Security
## Perimeter
Atlas OS is built so that a single operator can run ~24 public services from one VPS without exposing any of them to the open internet unguarded. Security is layered: every request passes an identity gate before it reaches an app, the hosting is EU-sovereign by design, secrets never touch git, and any action with real-world consequences (money, external communications, self-modification) requires a human to approve it.
All HTTP traffic enters through **Caddy** which:
- Terminates TLS (Let's Encrypt, auto-renew)
- Applies rate limiting
- Logs all requests
> See also: [[Architecture]] · [[Atlas-OS]] · [[Fleet-and-Mesh]] · [[AI-Stack]] · [[Identity]]
## Authentication
---
**Authentik** (self-hosted) provides SSO via `forward_auth`:
- Every service route checks with Authentik before proxying
- Unauthenticated requests get a 302 to the login page — never a data response
- Sessions are JWT-based with configurable expiry
- MFA supported (TOTP, WebAuthn)
## At a glance
## Network isolation
| Layer | Control | What it protects |
|---|---|---|
| Edge | Caddy (automatic TLS) | All inbound traffic is HTTPS |
| Identity | Authentik `forward_auth` on the embedded outpost | Single sign-on gate in front of apps |
| Auth strength | MFA | Account takeover |
| Sovereignty | Single Hetzner VPS in NL/DE (EU) | Jurisdiction / data residency |
| Private spine | Tailscale (`tailscale serve`) | Internal-only services, never public |
| Secrets | Vaultwarden + `/opt/atlas/secrets` (chmod 600) | Credential exposure |
| Source control | `.gitignore` enforced | Secrets leaking into git history |
| Recovery | Nightly backups | Data loss |
| Autonomy | AI policy gate (human approval) | Unauthorized money / comms / self-modify |
- Internal services (cockpit, LLM router, DBs) bind to `127.0.0.1` only
- Admin APIs bind to the Tailscale interface (`100.x.x.x`) only
- Public internet never reaches internal ports directly
---
## AI agent gates
## The SSO gate (Authentik `forward_auth`)
The Atlas Brain respects a policy file that hard-blocks autonomous action for:
- Any financial transaction
- Any external communication (email, WhatsApp send)
- Any self-modification (config changes, code deploy)
Every public hostname is fronted by **Caddy**, which terminates TLS and then asks **Authentik** whether the request is allowed before the upstream app ever sees it. This is done with Authentik's `forward_auth` integration running on its **embedded outpost** — Caddy makes a sub-request to the outpost for each incoming request, and only forwards the request to the app if the outpost returns an authenticated session.
These always require human approval in the Control screen.
```mermaid
%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%%
flowchart LR
U[Browser] -->|HTTPS| C[Caddy TLS edge]
C -->|forward_auth sub-request| O[Authentik embedded outpost]
O -->|authenticated?| C
C -->|allowed| A[App: Odoo / Open WebUI / Nextcloud / ...]
C -->|denied -> login| L[Authentik login + MFA]
L --> O
```
## Secrets management
Practical consequences of this model:
- No secrets in git (`.gitignore` enforced)
- Vaultwarden (self-hosted) for human-facing passwords
- Env files on the VPS in `/opt/atlas/secrets/` (not world-readable)
- Rotation: manual — planned for automated rotation via Vault/n8n
- **One front door.** A user signs in once at Authentik and gains access to the apps their identity is permitted to use, rather than logging into each service separately.
- **Apps are not directly reachable.** Because the gate sits at the edge, an unauthenticated request to a protected app is bounced to the Authentik login flow.
- **Admin identity:** `atlasshb` is the administrative identity for the platform.
## What to audit after forking
Identity tooling itself — **Authentik** (the identity provider) and **Vaultwarden** (the password/secret vault) — lives in the **Identity** category of [[Atlas-OS]].
1. Change all default passwords (Authentik akadmin, Forgejo, etc.)
2. Rotate the Evolution API key
3. Disable Authentik user registration if not needed
4. Review Caddy rate-limit thresholds for your traffic
5. Set up Uptime Kuma alerts for all services
---
## Multi-factor authentication (MFA)
Authentication is protected with **MFA**, so a leaked or guessed password alone is not sufficient to reach the platform. Because authentication is centralized at the Authentik gate, MFA is enforced at the single choke point rather than re-implemented per app.
---
## EU sovereignty (no US Cloud Act)
Atlas OS runs on a **single Hetzner VPS hosted in the EU (NL/DE)**. This is a deliberate jurisdictional choice:
- **EU-sovereign hosting.** Data resides in the European Union under EU jurisdiction.
- **No US Cloud Act exposure.** The platform does not depend on US-headquartered cloud providers, so it is not subject to the US Cloud Act's reach over data held by such providers.
This sovereignty posture covers the whole stack — the ~55 Docker containers and ~24 public services described in [[Architecture]] all run on that one EU box.
---
## Network model — public vs. private
Not everything that runs on the VPS is meant to be public. Atlas OS separates the two cleanly:
| Exposure | Mechanism | Examples |
|---|---|---|
| **Public** | Caddy + Authentik `forward_auth` | The ~24 public services |
| **Private** | Tailscale (`tailscale serve`) | Internal-only services, **never public** |
- **Tailscale** provides a private spine. Internal services are published over the tailnet with `tailscale serve` and are **never exposed publicly**.
- **NATS mesh** carries node-to-node messaging across the fleet (round-trip proven). See [[Fleet-and-Mesh]].
- **MeshCentral** is used to remote-manage client POS devices and other endpoints — also covered in [[Fleet-and-Mesh]].
This split means that even if an attacker probes the public surface, the internal control-plane services are simply not addressable from the internet.
---
## Secrets model
Secrets are kept out of the application code and out of version control. There are two complementary stores:
| Store | Purpose | Protection |
|---|---|---|
| **Vaultwarden** | Interactive / shared credential vault | Behind the SSO gate + MFA |
| **`/opt/atlas/secrets`** | On-host secrets for services and scripts | Filesystem perms `chmod 600` (owner-only read/write) |
Rules that hold across the platform:
- **No secrets in git.** A `.gitignore` is enforced so credentials and secret files are never committed to the **Forgejo** repositories (see Ops in [[Atlas-OS]]).
- **Least-privilege filesystem access.** On-host secrets in `/opt/atlas/secrets` are mode `600`, readable only by their owner.
- **Vaultwarden as the system of record** for interactive credentials, itself gated by Authentik + MFA like every other app.
---
## The AI human-approval gate
Atlas runs an autonomous core (**Atlas Brain**, a reviewed-execution model) backed by the `kernel.sqlite` spine and an LLM router. Autonomy is deliberately bounded by a **policy gate** that **always requires human approval** for the highest-risk action classes:
| Action class | Requires human approval? |
|---|---|
| Spending / moving **money** | Yes — always |
| **External communications** (anything sent outside) | Yes — always |
| **Self-modification** of the system | Yes — always |
This means the AI layer can plan, draft, and execute reviewed work autonomously, but it cannot independently spend money, message the outside world, or rewrite itself — a human stays in the loop for those. The broader AI architecture (the LLM router at `localhost:8888`, local-first model selection, and the Headroom context proxy) is documented in [[AI-Stack]].
---
## Backups & recovery
- **Nightly backups** are taken to protect against data loss.
Combined with EU-sovereign hosting, this keeps both the **location** and the **recoverability** of data under operator control.
---
## Security principles summary
1. **Gate first.** No public app is reached without passing Authentik `forward_auth` at the Caddy edge.
2. **Strong auth.** MFA is enforced centrally.
3. **Stay sovereign.** One EU VPS (NL/DE), no US Cloud Act exposure.
4. **Keep private things private.** Internal services ride Tailscale (`tailscale serve`) and are never public.
5. **Guard secrets.** Vaultwarden + `/opt/atlas/secrets` (`600`), and `.gitignore` keeps secrets out of git.
6. **Human-in-the-loop for consequences.** Money, external comms, and self-modification always require human approval.
7. **Be able to recover.** Nightly backups.
---
_Related pages: [[Architecture]] · [[Atlas-OS]] · [[Identity]] · [[AI-Stack]] · [[Fleet-and-Mesh]]_

21
_Sidebar.md

@ -1,9 +1,12 @@
### Atlas OS
- [Home](Home)
- [Architecture](Architecture)
- [Services](Services)
- [AI Stack](AI-Stack)
- [Deploy](Deploy)
- [Academy](Academy)
- [Islamic Layer](Islamic-Layer)
- [Security](Security)
### 🛰️ Atlas OS Wiki
- [[Home]]
- [[Architecture]]
- [[App-Catalog]]
- [[AI-Stack]]
- [[Services]]
- [[Fleet-and-Mesh]]
- [[Remote-Desktop]]
- [[Academy]]
- [[Islamic-Layer]]
- [[Security]]
- [[Deploy]]