Local development workflow: tiered local loop plus a Codespaces devcontainer

[jrosseel]

Deploying to a dev silo is currently the only way to exercise a change end to end, which makes every iteration expensive. This issue captures a measured proposal for a local/remote development loop, plus the CI-side optimisations that make it viable.

Measured baseline

Declared resource requests, summed from apps/_infra/deploy-k8s/values.yaml and apps/postgres/helm/values.yaml:

Scope	CPU requests	RAM requests
Core silo (server, UI, channel-proxy, memory-gateway, artifact service/preprocessor/scanner, litellm, mcp-gateway)	~1.0	~1.8 Gi
PostgreSQL (CNPG + pooler + jobs)	~0.45	~0.75 Gi
Agent controller + managed runtime plane (on demand, not always-on)	~4.1	~8.2 Gi
Everything declared	5.14	10.0 Gi

Burst limits total 53 CPU / 53 Gi, which are ceilings rather than allocations. First-party images are ~640 MB compressed (~1.4 GB on disk) before k3s, PostgreSQL and Cognee. Empirical anchor: the full silo already runs in k3d on a GitHub runner with 4 vCPU / 15.6 GB, and is visibly saturated there — the API server refused connections and the pooler flapped during the 2026-08-19 runs.

Two obstacles found

1. Published images are linux/amd64 only. The ghcr index carries linux/amd64 plus an attestation entry, no arm64. On Apple Silicon, running the published set locally means QEMU emulation.
2. No local run orchestration exists. apps/opencrane has dev: tsx watch src/index.ts and opencrane-ui has an nx serve target, and OIDC has a documented --disable path that reverts the UI to token/dev auth — but nothing wires them to a database, and apps/opencrane/project.json declares no targets at all. The only cluster script in the repo is the CI smoke.

Proposed tiers

Tier	Runs	CPU	RAM	Disk
1. Frontend	nx serve opencrane-ui + Storybook against mocks	2	4 GB	~2 GB
2. Server + database (everyday default)	PostgreSQL container + tsx watch server + UI, dev auth	2–4	4–6 GB	~5 GB
3. Full silo in k3d	what develop-smoke.sh boots	6 (4 minimum)	10–12 GB (8 minimum)	25–30 GB

Tier 2 covers API, domain, persistence and UI-against-real-backend work with no Kubernetes tax. Tier 3 is only needed for chart, NetworkPolicy, identity and migration work.

Codespaces

Codespaces is the better host for Tier 3 and removes obstacle 1 outright, since it is native linux/amd64.

• k3d needs only the Docker-in-Docker devcontainer feature (containers, not VMs — no nested virtualisation).
• develop-smoke.sh:403 requires exactly curl docker git helm k3d kubectl openssl; jq is also used by the health assertion.
• Pin the devcontainer to the versions CI pins so local and CI stop drifting: Node 24, Helm v4.1.4, k3d v5.8.3.
• Machine sizing: 2-core/8 GB for Tier 2; 8-core/32 GB/64 GB for Tier 3 (4-core/16 GB works but is as saturated as CI, and the larger disk matters for k3d plus image churn).
• ghcr pulls authenticate with the built-in token, so the smoke's digest-based baseline image reuse works unchanged.
• Prebuilds are what make start-up pleasant (bake node_modules and the pinned tools), at the cost of Actions minutes and storage.

Open question: browser access to the k3d ingress. The silo binds hosts like testv4.develop-smoke.opencrane.test behind a self-signed cert and the smoke reaches it with curl --resolve; a forwarded *.app.github.dev URL sends a Host header the ingress rule will not match. Options, cheapest first: do UI work in Tier 2; kubectl port-forward straight to the SPA service, bypassing host matching; or a local values profile that also accepts the Codespaces hostname.

Prerequisite before building Tier 2

Confirm the server's minimum boot configuration — whether LiteLLM, Cognee and the memory gateway are hard requirements or can be stubbed/pointed at a dev cluster. That decides whether Tier 2 is wiring or needs a real dev mode.

Related CI optimisations

• Multi-arch (linux/arm64) publishing would additionally unlock Mac-local Tier 3; a Codespaces-first approach makes it optional rather than required.
• KEEP_CLUSTER=1 already exists in develop-smoke.sh; a thin local entry point around it turns a red CI smoke into an interactive debugging session instead of log archaeology.
• Remaining smoke and caching work is tracked in CI: remaining caching and job-split opportunities #678.

Checklist

• Confirm the server's minimum boot configuration (blocking for Tier 2)
• .devcontainer/ with Docker-in-Docker and CI-pinned Node/Helm/k3d/kubectl
• Prebuild configuration
• Tier 2 entry point: PostgreSQL container + target baseline SQL + tsx watch server + nx serve UI with dev auth
• Tier 3 entry point wrapping develop-smoke.sh with KEEP_CLUSTER=1
• Decide the k3d ingress browser-access approach
• Document both tiers under docs/ and the website Contributing section