diff --git a/README.md b/README.md index 2f36e95..5638cfc 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,225 @@ -# Atlas OS +
-Browser-native desktop environment for Atlas Corporation — a full PWA served behind Authentik SSO. +``` + █████╗ ████████╗██╗ █████╗ ███████╗ +██╔══██╗╚══██╔══╝██║ ██╔══██╗██╔════╝ +███████║ ██║ ██║ ███████║███████╗ +██╔══██║ ██║ ██║ ██╔══██║╚════██║ +██║ ██║ ██║ ███████╗██║ ██║███████║ +╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚══════╝ + O S · A I C o m m a n d C e n t e r +``` + +**A browser-native AI desktop — log in with your identity, get your data, run your tools.** +No install. Any device. One URL. + +![Status](https://img.shields.io/badge/status-live-brightgreen?style=flat-square) +![Stack](https://img.shields.io/badge/stack-Vanilla_JS_·_Authentik_·_Docker_·_Caddy-blue?style=flat-square) +![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square) +![Built by](https://img.shields.io/badge/built_by-Atlas_Corporation-orange?style=flat-square) + +
+ +--- + +## What it is + +Atlas OS is a Citrix-style browser desktop for solo founders and small teams. +Log in once with Authentik SSO → a desktop boots with live data from your actual systems: +bank transactions, CRM leads, email drafts, fleet status, and a kill-switch for your AI agents. + +**Live:** `https://command.atlascorporation.nl/os/` *(SSO required)* + +--- ## Screens -| Screen | Data | -|--------|------| -| Today | Daily brief, AI state | -| Money | Bank transactions | -| Inbox | Email + WhatsApp drafts | -| Pipeline | CRM leads | -| Fleet | POS terminals | -| Control | Kill-switch, spend cap | +| # | Screen | Live data | +|---|--------|-----------| +| 1 | **Today** | AI daily brief, accountability level | +| 2 | **Money** | Bank transactions (Enable Banking) | +| 3 | **Inbox** | Email + WhatsApp drafts, flagged items | +| 4 | **Pipeline** | CRM leads and deal status (Odoo) | +| 5 | **Fleet** | POS terminals, health, last-seen | +| 6 | **Control** | AI kill-switch, daily spend cap | + +--- + +## Architecture + +```mermaid +graph TB + subgraph Internet["Internet"] + User([User / Device]) + end + + subgraph Edge["Edge — Caddy reverse proxy"] + Caddy[Caddy TLS + rate limit] + end + + subgraph Identity["Identity — Authentik"] + Auth[Authentik SSO forward_auth] + end + + subgraph OS["Atlas OS"] + Desktop[Atlas OS PWA] + Cockpit[The Mind cockpit] + end + + subgraph Comms["Communications"] + Evolution[Evolution API WhatsApp] + Stalwart[Stalwart Mail SMTP/IMAP] + end + + subgraph Apps["Apps"] + Odoo[Odoo 19 CE CRM+ERP] + Nextcloud[Nextcloud 31 files+cal] + Firefly[Firefly III finance] + Paperless[Paperless-ngx docs] + N8N[n8n automation] + Forgejo[Forgejo git] + Vault[Vaultwarden passwords] + MeshCentral[MeshCentral remote] + end + + subgraph AI["AI Layer"] + Router[Atlas LLM Router local+cloud] + Brain[Atlas Brain autonomous agent] + end + + User --> Caddy + Caddy --> Auth + Auth --> Desktop + Auth --> Apps + Desktop --> Cockpit + Cockpit --> Odoo + Brain --> Router + Evolution --> Brain +``` + +--- + +## Service map + +| Category | Service | URL | +|----------|---------|-----| +| Identity | Authentik SSO | auth.atlascorporation.nl | +| Identity | Vaultwarden | vault.atlascorporation.nl | +| OS | Atlas OS PWA | command.atlascorporation.nl/os/ | +| OS | Command dashboard | command.atlascorporation.nl | +| AI | Open WebUI / chat | chat.atlascorporation.nl | +| AI | Atlas Brain | internal | +| Mail | Stalwart | mail.atlascorporation.nl | +| CRM / ERP | Odoo 19 CE | odoo.atlascorporation.nl | +| Files | Nextcloud 31 | cloud.atlascorporation.nl | +| Finance | Firefly III | money.atlascorporation.nl | +| Documents | Paperless-ngx | docs.atlascorporation.nl | +| Automation | n8n | n8n.atlascorporation.nl | +| Git | Forgejo | git.atlascorporation.nl | +| Remote access | MeshCentral | mesh.atlascorporation.nl | +| Monitoring | Uptime Kuma | uptime.atlascorporation.nl | +| WhatsApp | Evolution API | internal | +| Academy | Atlas Academy | atlasacademy.nl | +| POS | AtlasPOS | atlaspos.nl | + +--- + +## Repo structure + +``` +atlas-os/ +├── web/ +│ ├── os.html # Atlas OS desktop PWA (6 screens, 28KB) +│ └── sitemap.html # Live service map (all 24+ services) +├── scripts/ +│ ├── enis_monitor.py # WhatsApp monitor + LLM auto-reply +│ ├── enis_monitor.service # systemd unit template +│ └── *.py # Automation: finance, leads, reminders +├── patterns/ +│ ├── ANTI_IMPULSE_RULES.md # Build discipline +│ └── CLUSTER_THEN_POLISH.md # UX pattern +├── docs/ +│ ├── deployment.md # Full stack deployment guide +│ └── security.md # Security model +└── .gitignore # Blocks secrets, env files, credentials +``` + +--- ## Deployment -Served at `https://command.atlascorporation.nl/os/` behind Authentik forward_auth. -Cockpit APIs proxied server-side — no credentials in the browser. +### Prerequisites +- VPS (4 vCPU / 8 GB RAM minimum — Hetzner CPX32 recommended) +- Docker + Docker Compose +- Caddy (TLS + reverse proxy) +- Domain you control -## Tech stack +### Atlas OS (Caddyfile snippet) -Vanilla JS PWA · Authentik SSO · Evolution API (WhatsApp) · Caddy · Docker · Hetzner +```caddy +command.yourdomain.com { + forward_auth authentik-server:9000 { + uri /outpost.goauthentik.io/auth/caddy + copy_headers X-Authentik-Username X-Authentik-Name X-Authentik-Email + } + handle_path /os/* { + root * /opt/atlas/atlas-desktop + file_server + } +} +``` + +### WhatsApp monitor + +```bash +cp scripts/enis_monitor.py /opt/atlas/brain/ +cp scripts/enis_monitor.service /etc/systemd/system/atlas-enis-monitor.service +systemctl enable --now atlas-enis-monitor +``` + +The monitor only replies when the contact starts a message with `/atlas` — silent otherwise. + +--- + +## AI stack + +``` +User message + │ + ▼ +Atlas Brain (Python autonomous agent) + │ + ├── Local router (localhost:8888) + │ ├── atlas-fast LLaMA 1B labels, routing + │ ├── atlas-free hermes3 Dutch copy, summaries + │ ├── atlas-code Qwen Coder code completion + │ └── atlas-phi3 Qwen 7B reasoning + │ + └── Cloud fallback (free tier first) + ├── Groq llama-3.3-70b-versatile + ├── Cerebras llama-3.1-70b + └── Claude sonnet-4-6 (paid, last resort) +``` + +--- + +## Security model + +- **All public services behind Authentik** — unauthenticated = 302 to SSO login. +- **Sensitive APIs on Tailscale only** — cockpit, Odoo internal APIs never public. +- **No secrets in git** — `.gitignore` blocks `*.env`, `*.key`, `*.sqlite`, `secrets/`, `.auth`. +- **LLM guardrails** — WhatsApp brain hard-blocks passwords, personal finance, client data. +- **Human gate for critical actions** — money movement, external comms, self-modification all require approval via the Control screen. + +--- + +## Built by + +**Chaib Aarab** — [Atlas Corporation](https://atlascorporation.nl), Tilburg NL + +Solo founder building AI-native business tooling for SMEs. +Everything here was built incrementally while running actual client projects. + +--- + +*MIT License — see LICENSE* diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..e37b12f --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,58 @@ +# Deployment guide + +## Stack overview + +All services run as Docker containers on a single VPS, fronted by Caddy. +Authentik provides SSO with forward_auth — no per-service login required. + +## Minimum VPS spec + +| Resource | Minimum | Recommended | +|----------|---------|-------------| +| CPU | 4 vCPU | 8 vCPU | +| RAM | 8 GB | 16 GB | +| Disk | 80 GB SSD | 160 GB SSD | +| OS | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | + +## Directory layout on the VPS + +``` +/opt/atlas/ +├── atlas-desktop/ # Atlas OS static files +├── brain/ # The Mind: brain.py, state files +├── cockpit/ # Cockpit API (Python FastAPI) +├── evolution/ # WhatsApp bridge config +├── forgejo/ # Forgejo docker-compose +├── nextcloud/ # Nextcloud docker-compose +└── secrets/ # NOT in git — env files, keys +``` + +## Caddy + Authentik SSO pattern + +Every service uses the same forward_auth block: + +```caddy +service.yourdomain.com { + forward_auth authentik-server:9000 { + uri /outpost.goauthentik.io/auth/caddy + copy_headers X-Authentik-Username X-Authentik-Name X-Authentik-Email + } + reverse_proxy localhost:PORT +} +``` + +## Starting order + +1. Authentik (identity must be up first) +2. Caddy (depends on Authentik for forward_auth) +3. All other services (order-independent) +4. Atlas Brain / cockpit (depends on Odoo + Evolution) + +## Environment variables + +Create `/opt/atlas/secrets/` (not in git) with: +- `brain.env` — ANTHROPIC_API_KEY, LLM router URLs +- `odoo.env` — DB credentials +- `nextcloud.env` — DB credentials, admin password +- `evolution.env` — WhatsApp API key +- `router-secrets.env` — GROQ_API_KEY, CEREBRAS_API_KEY, OPENROUTER_API_KEY diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..6008244 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,46 @@ +# Security model + +## Perimeter + +All HTTP traffic enters through **Caddy** which: +- Terminates TLS (Let's Encrypt, auto-renew) +- Applies rate limiting +- Logs all requests + +## 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) + +## Network isolation + +- 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 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) + +These always require human approval in the Control screen. + +## Secrets management + +- 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 + +## What to audit after forking + +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