dtoro/oikos
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Move 2026-07-12-wails-desktop-app plan to done/
Some checks failed
ci / build-test (push) Has been cancelled
Details
ci / docker-build (push) Has been cancelled
Details

Browse Source 
Phase 0 deployed 2026-07-12. Phases 1.0–1.4 implemented 2026-07-13.
Plan complete.
This commit is contained in:
authentik Default Admin
2026-07-13 22:41:45 +02:00
parent 5d6d9e9040
commit 6b52c1ae57
3 changed files with 383 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

829
plans/done/2026-07-12-wails-desktop-app.md Normal file
View File

@@ -0,0 +1,829 @@
# 2026-07-12 — Wails desktop application
**Status:** Done — Phases 0.0–0.6 deployed to production (mac-mini, commit
`0c0f35a`, 2026-07-12). Phases 1.0–1.4 implemented (commit `5d6d9e9`,
2026-07-13) — pushed to main.
**Production deploy (2026-07-12):** merged to `main`, picked up by the
2-minute deploy poller (`scripts/deploy.sh`: pg_dump backup → rebuild →
rolling restart → health check), `healthy after 1s`. Verified post-deploy:
unauthenticated `/api/v1/*` now 401s (the dev-open bypass was live in
production before this — `OIKOS_ENV=dev` with no token set — so this closed
a real, currently-exploitable hole, not just future prep); `/healthz` stayed
open; nomos reconnected its MCP session with the new
`OIKOS_MCP_BEARER_TOKEN` and a real tool call round-tripped end to end
(`get_health_summary` via `/query`). A real random token was generated and
added to mac-mini's `.env` (not committed — gitignored) before deploy, so
the `${OIKOS_MCP_BEARER_TOKEN:-dev-token}` fallback in `docker-compose.yml`
never activated with the weak literal default.
**Deliberately not done as part of this deploy** (out of scope — a different
host/repo than "mac-mini", not touched): the Caddy LXC (121) and
`dtoro/caddy-conf`. Checked the real production Caddyfile directly — there is
**no `oikos.hubris.network` site block at all yet**, so the Authentik-bypass
risk (gap 1 below) doesn't apply yet; there's no public UI exposed to break.
`mcp.hubris.network` exists but still reverse-proxies to the old
pre-consolidation service on LXC 105 (`192.168.8.205:9810`), unrelated to
this stack — stale, but pre-existing and out of scope here. Exposing
`oikos.hubris.network` publicly (with the `@api` bypass this plan's
Caddyfile.oikos reference copy already has) is unstarted follow-up work, not
a regression from this deploy.
## Plan review — gaps found before starting Phase 0
Reviewed against the current codebase and the live Caddy topology
(`compose/caddy/Caddyfile.oikos`) before writing any code. Six gaps, each
with the resolution taken:
1. **Authentik forward-auth vs. bearer-token clients.** The deployed
`oikos.hubris.network` site gates every route (including `/agent/*` and,
after this plan, `/api/v1/*`) with `import authentik` — a browser-session
forward-auth check, not a header a non-browser client can supply. Closing
the dev-open gate (0.4) makes every API route require a bearer token, but
says nothing about how a bearer-token client (Wails, curl, a future mobile
client) gets past Authentik's login redirect in front of it. Same shape as
the existing `@enroll` bypass for `/api/v1/clients/enroll`.
**Resolution:** updated the reference copy
([Caddyfile.oikos](compose/caddy/Caddyfile.oikos)) with an `@api path
/api/v1/* /mcp /agent/*` bypass around `import authentik`, same pattern as
`@enroll`, and moved static-SPA serving into the `handle {}` fallback
(0.6). This repo's copy is not what's deployed — the real file lives in
`dtoro/caddy-conf` and auto-deploys from there — so the equivalent change
still needs to land there before a Wails client (or anything else that
can't complete Authentik's browser login) can actually reach the API in
production. Flagged explicitly as risk #6 below so it isn't discovered the
hard way.
2. **Nomos's own gateway (C1) is a parallel, unauthenticated path to the same
backend.** [2026-07-11-nomos-agent-code-review.md](2026-07-11-nomos-agent-code-review.md)'s
C1 finding — nomos's port 8092 has zero auth of its own — is still open.
Phase 0.3's CORS/auth work only touches `internal/httpapi` (the `api`
process); `cmd/nomos` is untouched. The architecture diagram in this plan
shows Caddy's `handle_path /agent/*` proxying straight to `:8092`,
bypassing `api`'s `combinedAuth` entirely and relying solely on Authentik.
Closing the API's dev-open gate does nothing for this path — nomos's
direct mesh-published port (`docker-compose.yml:133`) and
`nomos.hubris.network` remain reachable with no credential check at all.
**Resolution:** not fixed by this plan — flagged as a pre-existing,
independent gap (already tracked as C1) that the Wails desktop app
inherits rather than introduces. Added as risk #6 below so it isn't
mistaken for something Phase 0 closes.
3. **`github.com/go-chi/cors` isn't a dependency yet**, and the plan's sample
CORS config (`AllowCredentials: true` with a default `"*"` origin) is
spec-invalid — browsers and webviews reject a wildcard
`Access-Control-Allow-Origin` when credentials are requested. This API
authenticates via `Authorization: Bearer`, not cookies, so credentialed
CORS mode isn't needed at all. **Resolution:** drop `AllowCredentials`
from the middleware config in 0.3 rather than ship a setting that silently
breaks the first time an origin other than `*` is configured.
4. **Closing dev-open (0.4) breaks local `docker compose --profile dev up`
out of the box** — none of the compose services currently set a token, and
today they rely entirely on `OIKOS_ENV=dev` + devOpen. Worse: `cmd/nomos`
itself is an unauthenticated client of `api`'s `/mcp` endpoint and
`/api/v1/approvals/{id}/decision` (chat-assent approvals) —
`grep -rn "Authorization" cmd/nomos/*.go` returned nothing before this
fix. Closing dev-open without touching nomos would have broken nomos's own
connection to the API, not just local dev ergonomics; this wasn't called
out anywhere in the original plan text. **Resolution:** added a `token`
field threaded through `mcpClient`/`mcpClientPool` and `agent.apiToken`,
both reading `OIKOS_MCP_BEARER_TOKEN` (the same shared secret `api`
already validates static tokens against) and sent as `Authorization:
Bearer ...` on every request nomos makes to `api`. `docker-compose.yml`
sets `OIKOS_MCP_BEARER_TOKEN` (default `dev-token`) on both the `api` and
`nomos` services so local dev keeps working.
5. **0.2's `const API = apiBase('/api/v1')` pattern bakes in a stale origin.**
Module-level constants evaluate once, at import time — before
`main.ts`'s `initConfig()` runs (ES module imports are hoisted ahead of a
file's own top-level statements) and before `Config.svelte` or a
Wails-injected `window.__OIKOS_CONFIG__` can set `apiUrl`. A first-launch
Wails webview would resolve `API` to a relative path and try to fetch
`wails://.../api/v1/...`, which doesn't exist. **Resolution:** `api.ts`
keeps `BASE`/`API` as bare path prefixes (`/agent`, `/api/v1`, never
resolved to a URL) and lets `fetchWithAuth` call `apiBase()` fresh on
every request — the same fix pattern as gap 4's SSE snippet: resolve at
call time, not at module-load time.
6. **`api`'s own `/agent` reverse-proxy mount (to nomos) was never behind
`combinedAuth` — found while auditing every route for the dev-open
removal.** [server.go](../internal/httpapi/server.go)'s
`r.Mount("/agent", ...)` was registered directly on the base router,
unlike every other custom route (`/mcp`, `/api/v1/knowledge/recent`,
etc.), which all use `r.With(combinedAuth(cfg, false))`. Harmless while
dev-open made the whole API open anyway; a real hole the moment 0.4 closes
it — any request to `api`'s `/agent/*` would reach nomos with no
credential check at all, independent of C1 (nomos's *own* gateway on
:8092, still open) and independent of gap 1 (Caddy/Authentik). **Resolution:**
wrapped the mount in `combinedAuth(cfg, false)`, matching every other
route.
Also: 0.4's local-dev token delivery ended up simpler than described —
"Vite injects it into `window.__OIKOS_CONFIG__` at dev time" isn't needed at
all for the relative-path dev case. The Vite proxy (0.2) already injects
`Authorization: Bearer $OIKOS_API_TOKEN` server-side on every proxied
`/api`/`/agent` request, so relative-path fetches during `npm run dev` are
authenticated before they leave the dev server — no client-side config
needed. `window.__OIKOS_CONFIG__` injection is still exactly what Phase 1's
Wails shell needs (absolute URL, no dev proxy to lean on).
Also: 0.3's SSE-auth snippet checks `GetActor(r.Context()) == nil` *inside*
`serveSSE` and validates the query token there — but `serveSSE` only runs
after `combinedAuth` has already accepted or rejected the request, and
`combinedAuth` requires a header today, so `EventSource` requests (no custom
headers) never reach `serveSSE` at all; they 401 in the middleware first.
**Actual implementation:** `combinedAuth` itself takes an `allowQueryToken
bool`; when set (only for the `/api/v1/events/stream` route) it falls back to
`?token=` when the `Authorization` header is absent, before running the same
OIDC/static validation as every other route. This reuses all existing auth
logic instead of duplicating a static-token-only path inside `serveSSE`, and
keeps the gate at the middleware layer rather than half-open inside the
handler. The static-token comparison itself was extracted into
`staticTokenActor(cfg, raw)`, shared between the header and query-param
paths.
## Goal
Transform the Oikos control room into a native desktop application using
[Wails](https://wails.io), built on top of a clean client/server split. The
server (API, MCP, scheduler, notifier, Nomos) stays on the homelab as a
long-running service. The client (SPA) is separated from the server binary and
deployed independently — any browser talks to the server over HTTP. The Wails
app is a thin native client: it loads the same SPA in a webview, configured
with the server URL and auth token, and adds system tray, native notifications,
auto-start, and auto-update.
---
## Architecture
```
┌────────────────────────────────────────────────────────────┐
│ Server (homelab, permanent) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ oikos api │ │ oikos sched │ │ oikos notif │ │
│ │ :8090 │ │ (observe) │ │ (Matrix) │ │
│ │ REST + SSE │ └──────────────┘ └──────────────┘ │
│ │ MCP /mcp │ │
│ └──────┬───────┘ ┌──────────────┐ │
│ │ │ nomos serve │ │
│ ├──────────┤ :8092 │ │
│ │ MCP │ /agent/* │ │
│ │ └──────┬───────┘ │
│ │ │ │
│ └────────┬────────┘ │
│ ┌──────▼──────┐ │
│ │ Postgres │ │
│ └─────────────┘ │
│ │
│ Caddy: /api/* → :8090 /agent/* → :8092 /mcp → :8090 │
│ / → static SPA (web/dist/) │
└───────────────────────┬────────────────────────────────────┘
│ HTTPS (bearer auth or OIDC)
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Browser │ │ Wails app │ │ CLI/mobile │
│ (SPA at /) │ │ (SPA in │ │ (future) │
│ │ │ webview) │ │ │
└──────────────┘ └─────────────┘ └─────────────┘
```
### Server
The existing server roles (`oikos api`, `oikos scheduler`, `oikos notifier`,
`nomos serve`, Postgres) run on the homelab mac-mini as systemd services —
unchanged. The SPA is no longer embedded in the `oikos` binary; it's a
standalone static build served by Caddy at `/`. The API routes (`/api/v1/*`,
`/mcp`, `/healthz`) don't conflict with root, and the old root redirect is
removed, so no path prefix is needed.
### Clients
Any HTTP client that speaks the REST API + bearer auth. The SPA is the
canonical client, deployed as static files. The Wails app wraps the same SPA
in a native webview. Future clients (CLI, mobile) use the same API.
---
## Stack
**Server:** existing Go code in `internal/` — no changes. `cmd/oikos` removes
the SPA embed and `/ui/*` routes. Caddy serves `web/dist/` at `/` with SPA
fallback.
**SPA:** existing Svelte 5 + Vite + Tailwind 4 + shadcn-svelte in `web/`.
API base URL and auth token become runtime-configurable. `base: '/'` — no
path prefix needed since the SPA is served at root.
**Desktop:** Wails v3 (Go + webview). The Wails app is a thin shell:
- Embeds the SPA as static assets (Wails's `go:embed`-based asset system)
- Reads server URL + token from OS keychain at startup, injects into webview
- SPA talks to the remote server over HTTPS — same as the browser
- No Go backend, no Postgres connection, no bundled sidecars
- Native shell: system tray, notifications, auto-start, auto-update,
window persistence
---
## Phase 0 — Client/server split
This phase separates the SPA from the `oikos` binary and makes it a
standalone client. The Wails app depends on this split being done first.
### 0.1 — Remove SPA embed from the server
- **Delete `web/embed.go`** — the server no longer embeds `web/dist/`.
- **`cmd/oikos/main.go`** — remove `uiHandler()` (~35 lines). The
`httpapi.ListenAndServe()` signature no longer takes a `uiHandler` param;
pass `nil` and handle nil in `server.go`.
- **`internal/httpapi/server.go`** — remove the `/ui/*` and `/ui` routes
(~15 lines at `server.go:175-182`), and the root redirect to `/ui/`
(`server.go:183-185`).
- **`web/dist/.gitkeep`** — delete (no longer needed to keep backend-only
builds green).
- **Dockerfile** — remove the node/ui-builder stage and `COPY --from=` of
`web/dist/`. The 3-stage Dockerfile (node → go → runtime) becomes a
2-stage build (go → runtime). ~20 lines deleted.
~80 lines deleted. The `oikos api` binary is now API-only: REST, SSE, MCP,
healthz.
### 0.2 — Make SPA API base URL configurable and add auth interceptor
The SPA currently hardcodes relative paths and has no auth headers:
```ts
// web/src/lib/api.ts
const BASE = '/agent'
const API = '/api/v1'
```
Replace with a runtime-configuration module (`web/src/lib/config.ts`):
```ts
// web/src/lib/config.ts
interface OikosConfig {
apiUrl: string // e.g. "https://oikos.hubris.network"
token?: string // bearer token for auth
}
declare global {
interface Window {
__OIKOS_CONFIG__?: OikosConfig
}
}
let cfg: OikosConfig | undefined
export function initConfig(override?: OikosConfig) {
cfg = override ?? window.__OIKOS_CONFIG__
if (cfg?.token) {
localStorage.setItem('oikos_token', cfg.token)
if (cfg.apiUrl) localStorage.setItem('oikos_api_url', cfg.apiUrl)
}
}
export function getConfig(): OikosConfig {
if (!cfg) {
const token = localStorage.getItem('oikos_token')
const apiUrl = localStorage.getItem('oikos_api_url')
if (token || apiUrl) {
cfg = { apiUrl: apiUrl ?? '', token: token ?? undefined }
}
}
return cfg ?? { apiUrl: '' }
}
export function isConfigured(): boolean {
const c = getConfig()
return !!c.apiUrl && !!c.token
}
// Relative paths are used in dev (Vite proxy) and when the SPA shares an
// origin with the API server (Caddy reverse proxy). Absolute paths are used
// when the API server is on a different origin (Wails webview, remote access).
function apiBase(path: string): string {
const c = getConfig()
if (!c.apiUrl) return path // relative — relies on same-origin or Vite proxy
return `${c.apiUrl}${path}`
}
// ---- Auth fetch wrapper ----
// Replaces every raw fetch() call in api.ts. Prepends the API base URL
// (absolute when configured, relative when unset for Vite dev proxy) and
// adds the Authorization header.
async function fetchWithAuth(path: string, opts?: RequestInit): Promise<Response> {
const headers: Record<string, string> = {
'Content-Type': 'application/json',
...(opts?.headers as Record<string, string> ?? {}),
}
const c = getConfig()
if (c.token) {
headers['Authorization'] = `Bearer ${c.token}`
}
return fetch(apiBase(path), { ...opts, headers })
}
// SSE path builder — EventSource doesn't take headers, so pass the token
// as a query parameter (the SSE handler in server.go checks it alongside
// the Authorization header).
export function sseUrl(path: string): string {
const c = getConfig()
const url = apiBase(path)
if (!c.token) return url
const sep = url.includes('?') ? '&' : '?'
return `${url}${sep}token=${encodeURIComponent(c.token)}`
}
// Export for api.ts to use throughout
export { fetchWithAuth, apiBase }
```
Then `web/src/lib/api.ts` — replace every `fetch(...)` call with
`fetchWithAuth(...)`. Example:
```ts
// Before:
// const res = await fetch(`${API}/entities?${params}`)
// After:
import { fetchWithAuth, apiBase } from './config'
const API = apiBase('/api/v1')
const BASE = apiBase('/agent')
// ...
const res = await fetchWithAuth(`/api/v1/entities?${params}`)
```
**`web/src/lib/stores/events.ts`** — replace `new EventSource(...)` with
`new EventSource(sseUrl(...))`:
```ts
import { sseUrl } from '$lib/config'
// Before:
// source = new EventSource('/api/v1/events/stream')
// After:
source = new EventSource(sseUrl('/api/v1/events/stream'))
```
**`web/src/lib/stores/chat.ts`** — the chat SSE is POST + ReadableStream via
`fetch()`, which already goes through `streamChat` in `api.ts`. When the plan
says "replace every fetch(...) call", `streamChat` is included — the POST to
`/agent/chat` becomes `fetchWithAuth('/agent/chat', ...)`.
**`web/src/lib/stores/context.ts`** — `refreshContext()` calls
`fetchDashboardSummary()` and `fetchApprovals()` from `api.ts`. Those
already go through `fetchWithAuth`. No change needed here.
**`web/src/lib/stores/workspace.ts`** — calls `fetchPlan()` and
`fetchQuestions()` from `api.ts`. No change needed.
**`web/src/main.ts`** — call `initConfig()` before mounting the app:
```ts
import { initConfig, isConfigured } from '$lib/config'
initConfig()
const app = mount(isConfigured() ? App : Setup, {
target: document.getElementById('app')!
})
export default app
```
This is the single largest frontend change: ~40 `fetch()` calls spread across
`api.ts` (all routes), `stores/events.ts` (EventSource), and the chat stream.
Each gets replaced with `fetchWithAuth()` or `sseUrl()`.
**`web/vite.config.ts`** — `base: '/'` (remove `/ui/` prefix, since the SPA
is served at root after the split). The dev proxy stays — same origin in dev
means relative paths work. After 0.4 closes the dev-open auth gate, inject
the token via a `configure` hook:
```ts
import { svelte } from '@sveltejs/vite-plugin-svelte'
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [tailwindcss(), svelte()],
base: '/',
resolve: {
alias: { $lib: '/src/lib' }
},
build: {
outDir: 'dist',
emptyOutDir: true
},
server: {
proxy: {
'/api': {
target: 'http://localhost:8090',
configure: (proxy) => {
proxy.on('proxyReq', (proxyReq) => {
const token = process.env.OIKOS_API_TOKEN
if (token) proxyReq.setHeader('Authorization', `Bearer ${token}`)
})
}
},
'/agent': {
target: 'http://localhost:8092',
rewrite: (path) => path.replace(/^\/agent/, ''),
configure: (proxy) => {
proxy.on('proxyReq', (proxyReq) => {
const token = process.env.OIKOS_API_TOKEN
if (token) proxyReq.setHeader('Authorization', `Bearer ${token}`)
})
}
}
}
}
})
```
### 0.3 — Add SSE query-param auth and CORS to the API server
**SSE auth.** The SSE handler at `/api/v1/events/stream` currently relies on
`combinedAuth` middleware for bearer token validation. `EventSource` can't
send custom headers, so the SPA passes the token as a query param
(`?token=...`). The SSE handler needs to extract and validate it.
**`internal/httpapi/sse.go`** — in `serveSSE`, before using the context's
actor, check for a query-param token:
```go
func (s *Server) serveSSE(w http.ResponseWriter, r *http.Request) {
// If combinedAuth didn't set an actor (no Authorization header —
// EventSource can't send one), try the query param.
if GetActor(r.Context()) == nil {
token := r.URL.Query().Get("token")
if token != "" {
validateStaticToken(s.cfg, r, token)
}
}
// ... rest of SSE handler
}
```
Extract the static-token validation from `combinedAuth` into a shared helper
so both the middleware and the SSE handler use the same logic.
**CORS middleware.** Add CORS to the chi router. This is needed for Wails
(webview origin differs from the remote server) and local dev (Vite on
`:5173` vs server on `:8090`). For the browser production deployment (Caddy
serves both SPA and API from the same origin), it's a no-op.
**`internal/httpapi/server.go`** — add before the auth middleware:
```go
r.Use(cors.Handler(cors.Options{
AllowedOrigins: []string{cfg.CORSAllowedOrigin},
AllowedMethods: []string{"GET", "POST", "PATCH", "DELETE", "OPTIONS"},
AllowedHeaders: []string{"Authorization", "Content-Type", "If-Match"},
AllowCredentials: true,
MaxAge: 86400,
}))
```
**`internal/config/config.go`** — add `CORSAllowedOrigin string`, populated
from `OIKOS_CORS_ORIGIN`. Default: `"*"` in dev, the Caddy site URL in prod.
~30 lines added.
### 0.4 — Auth: close the dev-open gate
Currently `combinedAuth` opens the gate when `OIKOS_ENV=dev` and no tokens
are set (`server.go:228`). After the split, a client from any origin can hit
the API — the dev-open path is a security hole.
- **Remove the `devOpen` path** from `combinedAuth` — every request must
carry a valid bearer token (via `Authorization` header or `?token=` query
param for SSE).
- **For local dev:** set `OIKOS_API_TOKEN=dev-token` and the SPA reads it
from `OIKOS_API_TOKEN` env var (Vite injects it into
`window.__OIKOS_CONFIG__` at dev time, and the Vite proxy forwards it).
- **Browser (production):** the SPA's `Config.svelte` page accepts a static
token (stored in `localStorage`). OIDC login flows are a follow-on
milestone.
- **Desktop (production):** the Wails app reads the token from the OS
keychain and injects it into `window.__OIKOS_CONFIG__` before the webview
loads.
### 0.5 — SPA config page (first-launch / setup)
The SPA needs a page for entering the server URL and auth token on first
launch. This page also serves as the foundation for future OIDC login.
New file `web/src/pages/Config.svelte`:
- Two fields: "Server URL" (text input) and "Token" (password input)
- "Connect" button: calls `fetchWithAuth('/api/v1/dashboard/summary')` to
validate, stores in `localStorage` on success, calls `initConfig()` to
refresh runtime config, navigates to `#/overview`
- Tabs placeholder for future OIDC flow: "Token", "Login with Authentik"
(the second tab is disabled with "coming soon")
- Error state: connection failed, wrong token, server unreachable
`web/src/App.svelte` — check `isConfigured()` at mount. If false, render
`Config.svelte` instead of the sidebar. On successful config, transition to
the full app.
`web/src/main.ts` — simplify to always mount `App.svelte` (the config check
lives in App.svelte's mount hook, not in main.ts):
```ts
import { mount } from 'svelte'
import App from './App.svelte'
import './app.css'
import { initConfig } from '$lib/config'
initConfig()
mount(App, { target: document.getElementById('app')! })
```
### 0.6 — Deploy SPA as standalone static files
The SPA is built with `base: '/'` and served by Caddy at `/` with SPA
fallback. API routes take priority (explicit `handle_path` blocks in Caddy).
**Caddy config** (add to the existing `compose/caddy/Caddyfile.oikos`):
```
handle {
root * /var/www/oikos-ui
file_server
try_files {path} /index.html
}
```
The `index.html` doesn't need a placeholder (`__OIKOS_API_URL__`) in the
Caddy deployment case — the SPA and API share an origin, so relative paths
work and `__OIKOS_CONFIG__` only needs `apiUrl` unset. The token is entered
by the user on the Config page and stored in `localStorage`.
**Build + deploy:**
```makefile
ui: ## Build the SPA for standalone deployment
cd web && npm run build
deploy-ui: ui ## Deploy SPA to the Caddy host
scp -r web/dist/* mac-mini:/var/www/oikos-ui/
ssh mac-mini sudo systemctl reload caddy
```
**Dockerfile** (server image, no Node required):
```dockerfile
# Stage 1: Build Go binary
FROM golang:1.26 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o oikos -tags timetzdata ./cmd/oikos
# Stage 2: Runtime
FROM debian:bookworm-slim
COPY --from=builder /app/oikos /usr/local/bin/oikos
EXPOSE 8090
ENTRYPOINT ["oikos"]
```
Drops the node builder stage entirely. The UI is built and deployed
separately.
### 0.7 — Verification
```
# Server
oikos api # API + SSE + MCP, no UI
curl localhost:8090/healthz # {"status":"ok"}
curl -H "Authorization: Bearer dev-token" \
localhost:8090/api/v1/dashboard/summary # data
# SPA (dev)
OIKOS_API_TOKEN=dev-token npm run dev # Vite at :5173, proxy to :8090
open http://localhost:5173/ # Config page (enter URL + token)
# → Overview with live data
# SPA (production test)
cd web && npm run build
caddy file-server -root dist --listen :3000 # serve SPA locally
# Run oikos api separately, open http://localhost:3000,
# enter apiUrl=http://localhost:8090 + token on Config page
```
---
## Phase 1 — Wails desktop app
Built on top of the split. The Wails app is a thin native wrapper around the
same SPA, configured to talk to the deployed server over HTTPS. No bundled
Go server, no Postgres connection, no nomos sidecar.
### 1.0 — Scaffold and window (1 session)
Create the Wails project with a native window loading the built SPA.
**`cmd/desktop/main.go`** — Wails v3 app:
- On startup: read config from OS keychain (`keyring` package or Wails
secrets plugin). Keys: `oikos_server_url`, `oikos_token`.
- If no config in keychain: load the SPA anyway — `Config.svelte` handles
first-launch setup.
- If config exists: inject `window.__OIKOS_CONFIG__` before the webview
mounts. Wails v3's `AssetsHandler` can mutate `index.html` before serving:
```go
assetsHandler: func(ctx context.Context, name string) (string, []byte, error) {
if name == "index.html" {
b, _ := assets.ReadFile("index.html")
html := strings.Replace(string(b),
`<script>window.__OIKOS_CONFIG__ = {};</script>`,
fmt.Sprintf(`<script>window.__OIKOS_CONFIG__ = %s;</script>`, configJSON),
1)
return "index.html", []byte(html), nil
}
b, _ := assets.ReadFile(name)
return name, b, nil
}
```
`index.html` includes a placeholder `<script>` tag that gets replaced:
```html
<script>window.__OIKOS_CONFIG__ = {};</script>
<script type="module" src="/src/main.ts"></script>
```
- Window: title "Oikos — Control Room", 1400×900, min 1024×700, dark
title bar (`mac.TitleBarStyleHiddenInset` or equivalent dark mode).
- Wails embeds `web/dist/` into the binary (via `//go:embed all:dist` in
the Wails project or the standard Wails asset system).
**`cmd/desktop/wails.json`** — Wails project config:
```json
{
"name": "oikos-desktop",
"frontend:dir": "../../web",
"frontend:build": "npm run build",
"frontend:dev:watcher": "npm run dev"
}
```
**`Makefile`**:
```makefile
desktop: ui ## Build the Wails desktop app
wails build -clean -o oikos-desktop
```
**Dev loop for the desktop app:**
```sh
# Terminal 1: run the server locally (or point at remote)
OIKOS_API_TOKEN=dev-token oikos api
# Terminal 2: start Wails in dev mode (hot-reload, connects to Vite)
cd cmd/desktop && wails dev
```
**`web/vite.config.ts`** — add `base: '/'` (already done in 0.2). No
Wails-specific Vite config needed since Wails v3 uses the standard Vite dev
server.
**Verify:**
```sh
OIKOS_SERVER_URL=https://oikos.hubris.network OIKOS_DESKTOP_TOKEN=... make desktop
./oikos-desktop
# Window opens → Config page (if no keychain entry) or Overview with live data
```
### 1.1 — Native shell features (1 session)
- **System tray** (Wails v3 `application.NewSystemTray`):
- Oikos logo icon (from `web/public/favicon.svg`)
- Menu: "Open Control Room" (focus/restore window), "Pending Approvals: N"
(fetched via backchannel HTTP call from Go, not the SPA), separator,
"Quit"
- When window is closed: minimize to tray instead of quitting (set
`HideOnClose`)
- **Native notifications** (`application.Notification`):
- A backchannel goroutine polls `GET /api/v1/dashboard/summary` every 30s
(separate HTTPS client in Go, independent of the webview)
- Fires OS notification when `approvals_pending` or `signals_by_severity.critical`
increases since last poll
- Click notification → `Window.Restore()` + send a message to the SPA via
Wails events to navigate to the relevant page
- **Window persistence**: remember size/position via Wails v3
`window.PersistState` or a JSON file in `~/.config/oikos/window.json`
- **Auto-start on login** (macOS):
- During setup flow, offer a checkbox: "Start automatically on login"
- Writes a LaunchAgent plist to `~/Library/LaunchAgents/com.hubris.oikos-desktop.plist`
that runs the binary on login
- Linux equivalent: `~/.config/autostart/oikos-desktop.desktop`
**Verify:** Close window → app stays in tray. New approval arrives → OS
notification appears with count. Click notification → window opens to Ops
page. Restart machine → app opens automatically on login.
### 1.2 — Token management (1 session)
- **First launch**: `Config.svelte` prompts for server URL + token (same
page as the browser SPA's setup)
- On "Connect" success, `Config.svelte` calls a Wails binding
`SaveConfig(apiUrl, token)` that stores in the OS keychain:
```go
func (a *App) SaveConfig(apiUrl string, token string) error {
keyring.Set("oikos_server_url", apiUrl)
keyring.Set("oikos_token", token)
return nil
}
```
- **Subsequent launches**: Wails reads keychain, injects config, SPA skips
Config page
- **Logout**: "Log out" menu item in system tray clears keychain and
refreshes the webview → `Config.svelte` appears
**Verify:** Enter URL + token on first launch, quit, reopen → skips setup
and loads Overview.
### 1.3 — Auto-update (1 session)
- Check Gitea releases (or a configured update URL) on startup and every
6 hours
- Wails v3 update plugin or a custom Go goroutine: `GET /releases/latest` →
compare semver → download binary → verify checksum → prompt restart
- Update manifest published alongside each release:
`oikos-desktop-darwin-arm64.json` with `version`, `url`, `sha256`
**Verify:** Build v1.0.0, publish v1.0.1 → app detects update, downloads,
prompts restart. After restart, version is 1.0.1.
### 1.4 — Distribution and packaging (1 session)
- **macOS**: `.app` bundle via `wails build`, code-sign with Apple
Developer ID, notarize via `xcrun notarytool`
- Bundle ID: `com.hubris.oikos-desktop`
- Entitlements: network client, keychain access
- **Linux**: `.deb` and AppImage via `wails build` + packaging scripts
- **CI**: `.gitea/workflows/desktop.yml` — builds all targets on tag push,
uploads artifacts to Gitea releases
- **AGENTS.md** update: document the desktop app as a first-class client
**Verify:** Download `.app` on a fresh Mac, open → first-launch setup →
connect to the homelab → full app works with zero dev tools.
---
## What does NOT change
- `internal/` — every package imported as-is. Zero modifications.
- `cmd/oikos/` — minus the SPA embed (0.1), the `oikos` binary is unchanged.
- `cmd/nomos/` — unchanged. The desktop app talks to nomos through the
server's `/agent` reverse proxy — same as the browser.
- `web/` — SPA source shared between browser and desktop builds. Gains
`config.ts` (auth interceptor), `Config.svelte` (setup page), and
`vite.config.ts` drops `/ui/` prefix + adds proxy token injection. All
existing pages, components, stores, hooks reused.
- `api/openapi.yaml` — unchanged.
- `seeds/` — unchanged.
- `docker-compose.yml` — server deployment unchanged (minus the Dockerfile
losing the UI build stage).
---
## Risks and open questions
1. **Wails v3 maturity.** v3 is newer than v2. Fallback: Wails v2 — same
architecture (Go + webview + embedded assets), different Go APIs. Scope
of impact: one file (`cmd/desktop/main.go`). The thin-wrapper approach
means the Wails API surface is ~50 lines of Go — trivially portable.
2. **OIDC login flow.** The browser SPA needs an OIDC redirect flow via
Authentik for production use (static tokens are fine for homelab dev but
not for external access). The `Config.svelte` page has a tab placeholder
for this. It's a separate milestone — for now, both browser and desktop
clients use a static bearer token configured at first launch.
3. **SSE query-param token in logs.** The token in `?token=...` appears in
Caddy access logs and server request logs. Mitigation: log redaction in
Caddy (`log { format filter { wrap json { fields { request>uri replace
"token=[^&]*" "token=***" } } } }`) and strip the query param from the
request logger in `server.go`.
4. **Webview CORS for embedded assets.** Wails loads the SPA from `wails://`
or `asset://` origin, making cross-origin requests to the remote server.
CORS middleware (0.3) handles this. The `Access-Control-Allow-Origin`
must match the webview's origin, which may change between Wails versions.
Mitigation: allow the configured origin explicitly; fall back to `*` for
dev; Wails v3 document its asset origin.
5. **Multiple clients hitting the same SSE broker.** Browser, Wails app, and
Nomos all connect to `/api/v1/events/stream`. The SSE broker already
handles multiple subscribers (fan-out via the subscriber list in
`sse.go`). Each client gets its own connection and replay. No change
needed.
6. **Deploy-time Caddy changes this plan does not make.** Two changes are
required outside this repo before Phase 0's auth tightening actually
protects anything in production, both in `dtoro/caddy-conf`:
- Add a bearer-token bypass around `import authentik` for `/api/v1/*` and
`/mcp` on `oikos.hubris.network`, mirroring the existing `@enroll`
bypass — otherwise closing the dev-open gate just adds a second,
redundant auth layer behind Authentik's browser-session check, and
non-browser clients (Wails, curl) can never get past the first one.
- Nomos's gateway (port 8092) has no auth of its own (C1, tracked in
[2026-07-11-nomos-agent-code-review.md](2026-07-11-nomos-agent-code-review.md)).
Phase 0 does not fix this — the mesh-published port and
`nomos.hubris.network` remain open regardless of anything done here.
Treat C1 as a co-requisite for a production Wails rollout, not
something this plan's auth work incidentally covers.