ai-agent/GOAL.md

GOAL — where ai-agent is going

North star

Be the open-source, intuitive, private and secure agent layer of any computer — to build and host websites and interact with your data.

Think Lovable, but open source and self-hosted: instead of a cloud service that builds apps for you on someone else's infrastructure, this is an agent layer you run on your own machine. It drives a coding agent to build things, hosts what it builds, and gives you a first-class UI over everything the agent touches — conversations, files, projects, costs, deploys.

Product pillars

1. Open source — the whole layer (backend, PWA, runner, deploy tooling) is inspectable and forkable. No black-box cloud builder.
2. Intuitive — a non-terminal user can spawn a session, watch it work in a live thread, and end up with a deployed site. The PWA is the product, not a debug view.
3. Private — your prompts, transcripts, code and data stay on your hardware. Nothing is shipped to a third party beyond the model API calls you configure.
4. Secure — authenticated at the edge, a trusted-caller gate on the API, and uploaded/user bytes never execute on the app origin. Agent writes are scoped to explicit mounts.

Architecture direction

• Zipgo under the hood. Site building and hosting go through zipgo: the agent builds a project, zipgo deploys it under a subdomain with TLS. The agent layer orchestrates; zipgo serves.
• Single Docker container. The target packaging is one container that any computer can run — agent runner, backend, UI and deploy path included. Today's split (host-side sidecar for the claude CLI, host-installed zipgo, homelab-specific mounts) is the gap to close: fold the runner into the container and make the host mounts optional, generic configuration.
• Self-update, inside the container. The layer keeps itself current without host intervention: it can rebuild/upgrade its own image and roll over via the existing health-gated blue-green mechanism (deploy.sh), with the update logic living inside the container rather than in host scripts.

What exists today vs. the goal

Today ai-agent is the homelab's Claude context viewer + session spawner (see CLAUDE.md): transcripts, file/token analytics, projects and services catalogs, spawn/resume/interrupt, blue-green deploys. That is the foundation — the conversation UX, the security model and the deploy machinery already exist.

The distance to the north star, roughly in order:

• Fold the host sidecar into the container. The Claude Code CLI is a self-contained native binary, so the image carries it and runs the same sidecar/sidecar.py on the container's loopback: RUNNER_IN_CONTAINER=1 (the standalone default) ⇒ the entrypoint starts the runner, points the backend's SIDECAR_URL at it, and watches the transcripts the CLI writes under its own $HOME. A standalone container spawns sessions with no host process at all — verified end to end (spawn → run → the turn renders in the viewer). The CLI authenticates from ANTHROPIC_API_KEY or a logged-in Claude home mounted at RUNNER_HOME. The homelab is unchanged: it leaves the flag off and keeps its host sidecar, which is what lets a run use the host's own hooks/skills/credentials.
• Bundle zipgo so "build me a site" ends in a hosted URL with no host-side tooling.
• Run with no homelab mounts. Every catalog now degrades to an empty list instead of erroring when its mount is absent, so the image boots against nothing but a workspace + a data dir. docker-compose.standalone.yml is that generic shape, and scripts/standalone-smoke.sh asserts it on a throwaway workspace (it catches a catalog that 500s on a missing mount — which is how the templates endpoint got fixed). A missing catalog is a valid state, not an error — keep it that way when adding one.
• Replace the remaining homelab-specific config with a first-run setup (the homelab docker-compose.yml still hardcodes ~8 host paths; the standalone file is the target shape, but there's no first-run wizard).
• Unblock the standalone build: publish @gabvdl/ui to public npm. frontend/.npmrc pulls the scope from the homelab's verdaccio on localhost:4873, so today the image only builds on the homelab (it runs anywhere). This gates the one-liner install below. Needs the pending NPM_TOKEN — a human/credential step.
• In-container self-update (image rebuild/upgrade + blue-green rollover triggered from inside).
• Publish as a standalone open-source repo with a one-liner install (docker run …). The repo split is done — this is now its own repo (extracted from the homelab monorepo with full history, public at git.gabvdl.xyz/gabrielvidal/ai-agent; the homelab keeps only a deployment shim in services/ai-agent/). The runner ships in-image, so what's left for the one-liner is the public @gabvdl/ui above (a build off-homelab).

Decisions in this service should move toward this target: prefer container-internal solutions over host scripts, generic config over homelab-hardcoded paths, and zipgo over bespoke hosting paths.