connectonion-studio 0.1.0__tar.gz

connectonion_studio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EvanYifanYang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectonion_studio-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: connectonion-studio
+Version: 0.1.0
+Summary: ConnectOnion Studio — local test cockpit for ConnectOnion agents: create, run, QR, live logs, Copy-for-Claude diagnostics.
+Author-email: EvanYifanYang <209575631+EvanYifanYang@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/EvanYifanYang/connectonion-studio
+Project-URL: Repository, https://github.com/EvanYifanYang/connectonion-studio
+Project-URL: Issues, https://github.com/EvanYifanYang/connectonion-studio/issues
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: segno>=1.6
+Requires-Dist: pydantic>=2
+Requires-Dist: ifaddr>=0.2
+Requires-Dist: psutil>=5.9
+Requires-Dist: filelock>=3.12
+Requires-Dist: connectonion>=1.2.1
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/EvanYifanYang/connectonion-studio/main/co_studio/frontend/assets/onion/onion_full.png" width="96" alt="ConnectOnion Studio" />
+
+# ConnectOnion Studio
+
+**A local test cockpit for [ConnectOnion](https://github.com/openonion/connectonion) agents.**
+
+Click toolkits to build an agent · scan its QR from the iOS app · watch live logs · copy a one-click diagnostics bundle straight into Claude.
+
+[![PyPI](https://img.shields.io/pypi/v/connectonion-studio.svg)](https://pypi.org/project/connectonion-studio/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#requirements)
+
+</div>
+
+---
+
+## Install
+
+```bash
+pipx install connectonion-studio      # or: pip install connectonion-studio
+co-studio                             # opens http://127.0.0.1:9900
+```
+
+That's it. The first launch **auto-creates your identity and activates your managed model key** (needs internet — it's your own key, one per user). Offline on first run? Just run `co auth` once you're back online.
+
+## What it does
+
+|  |  |
+|---|---|
+| 🧩 **Create** | Form: name · model · toolkit checkboxes → identity + QR ready instantly |
+| ▶️ **Run** | One process per agent, health-polled every 5 s, live state over WebSocket |
+| 📱 **QR** | Bare `0x` address — scan it in the iOS "Add agent" flow |
+| 📜 **Logs** | Live stdout + framework-logger streams, per agent |
+| 🩺 **Copy for Claude** | Paste-ready markdown diagnostics bundle, one click |
+| 🗑️ **Delete** | Moves to `~/.co-studio/trash/` — identity keys are never hard-deleted |
+
+**Toolkits:** `utility` · `web` · `files` · `shell` (approval-gated) · `image`
+
+## Requirements
+
+**Python 3.11+** · macOS, Linux, or Windows (WSL recommended)
+
+<details>
+<summary><b>API reference</b></summary>
+
+<br>
+
+| Method | Path | Returns |
+|---|---|---|
+| `GET` | `/api/agents` | `{"agents": [AgentSummary]}` |
+| `POST` | `/api/agents` | AgentDetail — body `{name, model, toolkits, trust}` |
+| `GET` | `/api/agents/{slug}` | AgentDetail |
+| `POST` | `/api/agents/{slug}/start` · `/stop` · `/restart` | `{"state": …}` |
+| `POST` | `/api/agents/{slug}/rename` | AgentSummary — body `{name}` |
+| `DELETE` | `/api/agents/{slug}` | `204` (moved to trash) |
+| `GET` | `/api/agents/{slug}/qr.svg` | SVG QR |
+| `GET` | `/api/agents/{slug}/diagnostics` | Markdown bundle |
+| `GET` | `/api/setup/status` | Doctor checks |
+| `WS` | `/ws/status` | Status frames (each change + every 5 s) |
+| `WS` | `/ws/agents/{slug}/logs` | `{"source": "stdout" \| "logger", "line": …}` |
+
+</details>
+
+<details>
+<summary><b>Storage &amp; internals</b></summary>
+
+<br>
+
+```
+~/.co-studio/agents/<slug>/   meta.json · agent.py · .env · .co/ · studio-stdout.log
+~/.co-studio/trash/           deleted agents (timestamped)
+```
+
+- Agent ports `8000–8099`, allocated by socket probe (busy ports skipped, re-probed at start).
+- `agent.py` is standalone — eject it anywhere and `python agent.py` still works (the announce IP-trim patch is inlined).
+
+</details>
+
+<details>
+<summary><b>Development (from source)</b></summary>
+
+<br>
+
+```bash
+git clone https://github.com/EvanYifanYang/connectonion-studio && cd connectonion-studio
+./install.sh
+.venv/bin/co-studio
+```
+
+| Env | Effect |
+|---|---|
+| `CONNECTONION_PATH=~/repo/connectonion ./install.sh` | Install the framework from a local checkout instead of PyPI |
+| `PYTHON=python3.12 ./install.sh` | Pick the interpreter |
+
+</details>
+
+## Security
+
+- The manager binds **`127.0.0.1:9900` only**.
+- Agent ports are **unauthenticated** and exposed on your LAN by `host()` — that is how the phone connects. **Don't run on hostile networks.**

connectonion_studio-0.1.0/README.md

@@ -0,0 +1,102 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/EvanYifanYang/connectonion-studio/main/co_studio/frontend/assets/onion/onion_full.png" width="96" alt="ConnectOnion Studio" />
+
+# ConnectOnion Studio
+
+**A local test cockpit for [ConnectOnion](https://github.com/openonion/connectonion) agents.**
+
+Click toolkits to build an agent · scan its QR from the iOS app · watch live logs · copy a one-click diagnostics bundle straight into Claude.
+
+[![PyPI](https://img.shields.io/pypi/v/connectonion-studio.svg)](https://pypi.org/project/connectonion-studio/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#requirements)
+
+</div>
+
+---
+
+## Install
+
+```bash
+pipx install connectonion-studio      # or: pip install connectonion-studio
+co-studio                             # opens http://127.0.0.1:9900
+```
+
+That's it. The first launch **auto-creates your identity and activates your managed model key** (needs internet — it's your own key, one per user). Offline on first run? Just run `co auth` once you're back online.
+
+## What it does
+
+|  |  |
+|---|---|
+| 🧩 **Create** | Form: name · model · toolkit checkboxes → identity + QR ready instantly |
+| ▶️ **Run** | One process per agent, health-polled every 5 s, live state over WebSocket |
+| 📱 **QR** | Bare `0x` address — scan it in the iOS "Add agent" flow |
+| 📜 **Logs** | Live stdout + framework-logger streams, per agent |
+| 🩺 **Copy for Claude** | Paste-ready markdown diagnostics bundle, one click |
+| 🗑️ **Delete** | Moves to `~/.co-studio/trash/` — identity keys are never hard-deleted |
+
+**Toolkits:** `utility` · `web` · `files` · `shell` (approval-gated) · `image`
+
+## Requirements
+
+**Python 3.11+** · macOS, Linux, or Windows (WSL recommended)
+
+<details>
+<summary><b>API reference</b></summary>
+
+<br>
+
+| Method | Path | Returns |
+|---|---|---|
+| `GET` | `/api/agents` | `{"agents": [AgentSummary]}` |
+| `POST` | `/api/agents` | AgentDetail — body `{name, model, toolkits, trust}` |
+| `GET` | `/api/agents/{slug}` | AgentDetail |
+| `POST` | `/api/agents/{slug}/start` · `/stop` · `/restart` | `{"state": …}` |
+| `POST` | `/api/agents/{slug}/rename` | AgentSummary — body `{name}` |
+| `DELETE` | `/api/agents/{slug}` | `204` (moved to trash) |
+| `GET` | `/api/agents/{slug}/qr.svg` | SVG QR |
+| `GET` | `/api/agents/{slug}/diagnostics` | Markdown bundle |
+| `GET` | `/api/setup/status` | Doctor checks |
+| `WS` | `/ws/status` | Status frames (each change + every 5 s) |
+| `WS` | `/ws/agents/{slug}/logs` | `{"source": "stdout" \| "logger", "line": …}` |
+
+</details>
+
+<details>
+<summary><b>Storage &amp; internals</b></summary>
+
+<br>
+
+```
+~/.co-studio/agents/<slug>/   meta.json · agent.py · .env · .co/ · studio-stdout.log
+~/.co-studio/trash/           deleted agents (timestamped)
+```
+
+- Agent ports `8000–8099`, allocated by socket probe (busy ports skipped, re-probed at start).
+- `agent.py` is standalone — eject it anywhere and `python agent.py` still works (the announce IP-trim patch is inlined).
+
+</details>
+
+<details>
+<summary><b>Development (from source)</b></summary>
+
+<br>
+
+```bash
+git clone https://github.com/EvanYifanYang/connectonion-studio && cd connectonion-studio
+./install.sh
+.venv/bin/co-studio
+```
+
+| Env | Effect |
+|---|---|
+| `CONNECTONION_PATH=~/repo/connectonion ./install.sh` | Install the framework from a local checkout instead of PyPI |
+| `PYTHON=python3.12 ./install.sh` | Pick the interpreter |
+
+</details>
+
+## Security
+
+- The manager binds **`127.0.0.1:9900` only**.
+- Agent ports are **unauthenticated** and exposed on your LAN by `host()` — that is how the phone connects. **Don't run on hostile networks.**

connectonion_studio-0.1.0/co_studio/__init__.py

@@ -0,0 +1,3 @@
+"""ConnectOnion Studio — local test cockpit for ConnectOnion agents."""
+
+__version__ = "0.1.0"

connectonion_studio-0.1.0/co_studio/__main__.py

@@ -0,0 +1,27 @@
+"""Entry point: serve on 127.0.0.1:9900 and open the dashboard in the browser."""
+
+from __future__ import annotations
+
+import argparse
+import threading
+import webbrowser
+
+import uvicorn
+
+from . import config
+from .app import create_app
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Start the loopback-only studio server; pop the dashboard unless --no-browser."""
+    parser = argparse.ArgumentParser(prog="co-studio", description="ConnectOnion Studio — local agent test cockpit.")
+    parser.add_argument("--no-browser", action="store_true", help="do not open the dashboard in a browser (headless/CI)")
+    args = parser.parse_args(argv)
+    url = f"http://{config.STUDIO_HOST}:{config.STUDIO_PORT}"
+    if not args.no_browser:
+        threading.Timer(1.2, webbrowser.open, args=(url,)).start()
+    uvicorn.run(create_app(), host=config.STUDIO_HOST, port=config.STUDIO_PORT, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

connectonion_studio-0.1.0/co_studio/api/__init__.py

@@ -0,0 +1 @@
+"""REST and WebSocket route modules."""

connectonion_studio-0.1.0/co_studio/api/agents.py

@@ -0,0 +1,150 @@
+"""REST endpoints for agent CRUD, lifecycle, QR, and diagnostics."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Response
+from fastapi.responses import PlainTextResponse
+from pydantic import BaseModel, Field
+
+from .. import config, creator, diagnostics, identity, logs, registry
+from ..registry import AgentMeta
+from ..supervisor import SUPERVISOR
+
+router = APIRouter(prefix="/agents", tags=["agents"])
+
+
+class CreateAgentBody(BaseModel):
+    """POST /api/agents payload."""
+
+    name: str = Field(min_length=1, max_length=80)
+    model: str = "co/gemini-2.5-flash"
+    toolkits: list[str] = ["utility"]
+    trust: str = "open"
+
+
+def summarize(meta: AgentMeta) -> dict[str, object]:
+    """AgentSummary per the API contract."""
+    return {
+        "slug": meta.slug,
+        "name": meta.name,
+        "address": meta.address,
+        "port": meta.port,
+        "model": meta.model,
+        "toolkits": meta.toolkits,
+        "trust": meta.trust,
+        "state": SUPERVISOR.state_of(meta.slug),
+        "created_at": meta.created_at,
+    }
+
+
+def detail(meta: AgentMeta) -> dict[str, object]:
+    """AgentDetail per the API contract (summary + paths + runtime signals)."""
+    agent_dir = registry.agent_dir(meta.slug)
+    endpoints, relay = logs.parse_runtime_signals(agent_dir / config.STDOUT_LOG_NAME)
+    return {
+        **summarize(meta),
+        "script_path": str(agent_dir / "agent.py"),
+        "co_dir": str(agent_dir / ".co"),
+        "endpoints_announced": endpoints,
+        "relay_ok": relay,
+        "last_error": SUPERVISOR.last_error_of(meta.slug),
+    }
+
+
+def _get_meta(slug: str) -> AgentMeta:
+    """Load meta or raise 404."""
+    meta = registry.load(slug)
+    if meta is None:
+        raise HTTPException(status_code=404, detail=f"no agent named '{slug}'")
+    return meta
+
+
+@router.get("")
+def list_agents() -> dict[str, object]:
+    """GET /api/agents."""
+    return {"agents": [summarize(meta) for meta in registry.load_all()]}
+
+
+@router.post("")
+def create_agent(body: CreateAgentBody) -> dict[str, object]:
+    """Create identity + QR-ready agent directory; does NOT start the process."""
+    try:
+        meta = creator.create(body.name, body.model, body.toolkits, body.trust)
+    except ValueError as exc:  # unknown toolkit or trust level
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except RuntimeError as exc:  # port range exhausted
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    return detail(meta)
+
+
+@router.get("/{slug}")
+def get_agent(slug: str) -> dict[str, object]:
+    """GET /api/agents/{slug}."""
+    return detail(_get_meta(slug))
+
+
+class RenameBody(BaseModel):
+    """POST /api/agents/{slug}/rename payload."""
+
+    name: str = Field(min_length=1, max_length=80)
+
+
+@router.post("/{slug}/rename")
+def rename_agent(slug: str, body: RenameBody) -> dict[str, object]:
+    """Rename an agent: update meta.json AND re-render agent.py so the name it advertises
+    matches (keeps its slug, identity, port, and folder). Restart to apply to a live process."""
+    name = body.name.strip()
+    if not name:
+        raise HTTPException(status_code=422, detail="name must not be blank")
+    with registry.locked():
+        meta = _get_meta(slug)
+        meta.name = name
+        registry.save(meta)
+        agent_dir = registry.agent_dir(slug)
+        (agent_dir / "agent.py").write_text(
+            creator.render(name, meta.model, meta.port, meta.toolkits, meta.trust)
+        )
+    return summarize(meta)
+
+
+@router.post("/{slug}/start")
+async def start_agent(slug: str) -> dict[str, str]:
+    """Spawn the agent process."""
+    return {"state": await SUPERVISOR.start(_get_meta(slug))}
+
+
+@router.post("/{slug}/stop")
+async def stop_agent(slug: str) -> dict[str, str]:
+    """Terminate the agent process group."""
+    _get_meta(slug)
+    return {"state": await SUPERVISOR.stop(slug)}
+
+
+@router.post("/{slug}/restart")
+async def restart_agent(slug: str) -> dict[str, str]:
+    """Stop then start the agent."""
+    return {"state": await SUPERVISOR.restart(_get_meta(slug))}
+
+
+@router.delete("/{slug}", status_code=204)
+async def delete_agent(slug: str) -> Response:
+    """Stop the agent and permanently delete its directory (identity, keys, logs)."""
+    _get_meta(slug)
+    await SUPERVISOR.stop(slug)
+    SUPERVISOR.forget(slug)
+    with registry.locked():
+        registry.delete(slug)
+    return Response(status_code=204)
+
+
+@router.get("/{slug}/qr.svg")
+def agent_qr(slug: str) -> Response:
+    """SVG QR of the bare 0x address for the iOS scan-to-add flow."""
+    meta = _get_meta(slug)
+    return Response(content=identity.qr_svg(meta.address), media_type="image/svg+xml")
+
+
+@router.get("/{slug}/diagnostics")
+def agent_diagnostics(slug: str) -> PlainTextResponse:
+    """The Copy-for-Claude markdown bundle."""
+    return PlainTextResponse(diagnostics.build(_get_meta(slug)), media_type="text/markdown")

connectonion_studio-0.1.0/co_studio/api/settings_api.py

@@ -0,0 +1,42 @@
+"""Studio settings: the agents storage location (with migration)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from .. import storage
+
+router = APIRouter(prefix="/settings", tags=["settings"])
+
+
+class StorageBody(BaseModel):
+    """POST /api/settings/storage payload."""
+
+    path: str
+
+
+@router.get("/storage")
+def get_storage() -> dict[str, str]:
+    """The agents directory in effect right now."""
+    return {"agents_dir": storage.current()}
+
+
+@router.post("/pick-folder")
+def pick_folder() -> dict[str, str]:
+    """Pop the native folder chooser and return the chosen path."""
+    path = storage.pick_folder()
+    if not path:
+        raise HTTPException(status_code=409, detail="No folder chosen.")
+    return {"path": path}
+
+
+@router.post("/storage")
+async def set_storage(body: StorageBody) -> dict[str, object]:
+    """Move existing agents to a new folder and switch the studio over to it."""
+    try:
+        return await storage.change(body.path)
+    except ValueError as exc:  # bad/rejected path
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except OSError as exc:  # move failed mid-flight
+        raise HTTPException(status_code=500, detail=f"Move failed: {exc}") from exc

connectonion_studio-0.1.0/co_studio/api/setup.py

@@ -0,0 +1,15 @@
+"""Setup status endpoint (doctor + auth/key checks)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from .. import setup_check
+
+router = APIRouter(prefix="/setup", tags=["setup"])
+
+
+@router.get("/status")
+def setup_status() -> dict[str, object]:
+    """GET /api/setup/status."""
+    return setup_check.status()

connectonion_studio-0.1.0/co_studio/api/ws.py

@@ -0,0 +1,82 @@
+"""WebSocket endpoints: fleet status pushes and per-agent log streams."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+from pathlib import Path
+from typing import Callable
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from .. import config, logs, registry
+from ..supervisor import SUPERVISOR
+from .agents import summarize
+
+router = APIRouter()
+
+
+def _status_frame() -> dict[str, object]:
+    """The {"type":"status","agents":[...]} frame."""
+    return {"type": "status", "agents": [summarize(meta) for meta in registry.load_all()]}
+
+
+@router.websocket("/ws/status")
+async def status_ws(websocket: WebSocket) -> None:
+    """Push a status frame on every state change and at least every 5 seconds."""
+    await websocket.accept()
+    queue = SUPERVISOR.subscribe()
+    try:
+        while True:
+            await websocket.send_json(_status_frame())
+            with suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(queue.get(), timeout=config.HEALTH_INTERVAL)
+    except (WebSocketDisconnect, RuntimeError):  # RuntimeError: send after client close
+        pass
+    finally:
+        SUPERVISOR.unsubscribe(queue)
+
+
+@router.websocket("/ws/agents/{slug}/logs")
+async def logs_ws(websocket: WebSocket, slug: str) -> None:
+    """Stream stdout and framework-logger lines as they arrive."""
+    if registry.load(slug) is None:
+        await websocket.close(code=4404)
+        return
+    await websocket.accept()
+    agent_dir = registry.agent_dir(slug)
+    stdout_path = agent_dir / config.STDOUT_LOG_NAME
+    queue: asyncio.Queue[dict[str, str]] = asyncio.Queue()
+
+    async def pump(source: str, get_path: Callable[[], Path | None]) -> None:
+        async for line in logs.follow(get_path):
+            await queue.put({"source": source, "line": line})
+
+    async def send_loop() -> None:
+        while True:
+            await websocket.send_json(await queue.get())
+
+    async def recv_loop() -> None:
+        # Nothing else reads the socket, so an idle client's disconnect would never
+        # surface (send_loop is parked on queue.get()). Draining receives lets a close
+        # wake us so the pump tasks don't leak forever.
+        while True:
+            message = await websocket.receive()
+            if message.get("type") == "websocket.disconnect":
+                return
+
+    tasks = [
+        asyncio.create_task(pump("stdout", lambda: stdout_path)),
+        asyncio.create_task(pump("logger", lambda: logs.logger_log_path(agent_dir))),
+        asyncio.create_task(send_loop()),
+        asyncio.create_task(recv_loop()),
+    ]
+    try:
+        done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        for task in done:
+            with suppress(WebSocketDisconnect, RuntimeError):
+                task.result()  # absorb the expected disconnect/close; re-raise anything else
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)

connectonion_studio-0.1.0/co_studio/app.py

@@ -0,0 +1,92 @@
+"""FastAPI application factory: API routers, websockets, and the static frontend."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager, suppress
+from typing import AsyncIterator
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse, HTMLResponse, Response
+from fastapi.staticfiles import StaticFiles
+
+from . import config, registry, setup_check
+from .api import agents, settings_api, setup, ws
+from .supervisor import SUPERVISOR
+
+
+def _auto_authenticate() -> None:
+    """Best-effort: mint THIS user's own managed key on first run, so no manual `co auth` is needed.
+
+    connectonion's auth is signature-based — no login/password/browser: it signs with the local
+    ~/.co Ed25519 key and the backend auto-creates the account. The key is always PER-USER, never a
+    shared/bundled secret. Silent no-op on any failure (offline, backend down, or a refactor of these
+    CLI internals); the onboarding screen still covers those cases and re-polls /api/setup/status.
+    """
+    if setup_check._has_managed_key():  # already activated → nothing to do
+        return
+    try:
+        from connectonion.cli.commands.auth_commands import authenticate
+        from connectonion.cli.commands.project_cmd_lib import ensure_global_config
+
+        if not (config.MAIN_CO_DIR / "keys" / "agent.key").exists():
+            ensure_global_config()  # auth needs a keypair to sign — create the ~/.co identity first
+        ok = authenticate(config.MAIN_CO_DIR, save_to_project=False, quiet=True)
+        state = "ok — managed key ready" if ok else "skipped (offline?); run `co auth` when online"
+        print(f"[co-studio] auto-auth {state}", flush=True)
+    except Exception as exc:  # noqa: BLE001 — never block startup on framework internals / network
+        print(f"[co-studio] auto-auth unavailable ({exc!r}) — run `co auth` manually if needed", flush=True)
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Run the doctor, kick off first-run auth, adopt orphan agents, and drive the health poll."""
+    registry.ensure_dirs()
+    # Background + best-effort so the server binds immediately; the key lands within a few seconds
+    # and the onboarding screen (2s poll) dismisses itself once /api/setup/status flips to key_ok.
+    auth_task = asyncio.create_task(asyncio.to_thread(_auto_authenticate))
+    for entry in setup_check.run_doctor():
+        mark = "ok  " if entry["ok"] else "FAIL"
+        print(f"[co-studio] doctor {mark} {entry['check']} — {entry['detail']}", flush=True)
+    SUPERVISOR.adopt_orphans()
+    poller = asyncio.create_task(SUPERVISOR.run())
+    yield
+    poller.cancel()
+    auth_task.cancel()
+    for task in (poller, auth_task):
+        with suppress(asyncio.CancelledError, Exception):
+            await task
+
+
+def create_app() -> FastAPI:
+    """Build the studio app: /api/*, /ws/*, and the zero-build frontend at /."""
+    app = FastAPI(title="ConnectOnion Studio", lifespan=_lifespan)
+
+    @app.middleware("http")
+    async def _always_revalidate(request, call_next):
+        """No heuristic caching: the browser must revalidate every asset each load,
+        so edits to the zero-build frontend show up on a plain reload (still cheap —
+        unchanged files come back as a 304 via StaticFiles' ETag/Last-Modified)."""
+        response = await call_next(request)
+        response.headers["Cache-Control"] = "no-cache"
+        return response
+
+    app.include_router(agents.router, prefix="/api")
+    app.include_router(setup.router, prefix="/api")
+    app.include_router(settings_api.router, prefix="/api")
+    app.include_router(ws.router)
+
+    for sub in ("assets", "css", "js"):
+        directory = config.FRONTEND_DIR / sub
+        if directory.is_dir():
+            app.mount(f"/{sub}", StaticFiles(directory=directory), name=sub)
+
+    @app.get("/", include_in_schema=False)
+    def index() -> Response:
+        """Serve the SPA (or a plain notice while the frontend is absent)."""
+        page = config.FRONTEND_DIR / "index.html"
+        if page.exists():
+            return FileResponse(page)
+        return HTMLResponse("<h1>ConnectOnion Studio</h1><p>frontend/ not built yet — the API is live under /api.</p>")
+
+    return app