Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
UI Server: Flask → FastAPI Migration
Background
vibe/ui_server.py is a 2,380-line, 74-route Flask app served by werkzeug.make_server(..., threaded=True). Every async helper from vibe/api.py is invoked through asyncio.run(coro) (9 sites), which spins up a fresh event loop per HTTP request.
This collides head-on with the long-lived singleton state in agent backends — most prominently OpenCodeServerManager, which caches aiohttp.ClientSession, asyncio.Lock, and (worst of all) asyncio.subprocess.Process objects. Subprocess transports bind their internal waiter Future to the loop that created them. The singleton outlives the loop. Any later request from a new loop that touches process.wait(), lock.acquire() etc. raises:
RuntimeError: got Future <Future pending> attached to a different loop
Two recent PRs (#282, #296) added defensive bandages: _process_loop / _lock_loop / _http_session_loop guards that detect and re-create per-loop primitives. These keep the lid on — but every new feature on the UI server (chat streaming, skills config, live agent state) is one missing guard away from re-introducing the bug, and Flask's WSGI threading model offers nothing better than asyncio.run.
The product direction makes this terminal: the UI is growing to host chat with an agent, agent configuration, skills configuration, and similar live, long-lived interactions. Chat in particular implies WebSocket or SSE — Flask + asyncio.run is the wrong substrate for that.
Goal
Replace the Flask + asyncio.run-per-request model with FastAPI + uvicorn (ASGI, single persistent event loop). Acceptance criteria:
- Every HTTP route in
vibe/ui_server.pyis preserved at the same path + method, returning the same response shape — the React UI inui/should not need any change. - All async helpers in
vibe/api.pyare reachable via directawaitfrom FastAPI handlers — noasyncio.run, norun_coroutine_threadsafefrom request paths. - The dedicated
vibe-oauth-loopdaemon thread (and the_submit_oauth_corohelper) is removed — FastAPI's uvicorn loop becomes the single UI loop, the OAuth service runs natively on it. - The OpenCodeServerManager
_process_loop/_lock_loop/_http_session_loopguards stay (defense in depth), but they should not trip in normal operation any more — verify via regression. - The test suite (currently ~112 hits across tests using
flask.Flask.test_client-style APIs) is migrated tofastapi.testclient.TestClient. Tests stay green. - A WebSocket-capable route exists end-to-end (one trivial echo route is enough; chat itself is out of scope for this PR) — proves the substrate is ready.
- Local install via
uv tool installstill works. The local Incus regression environment starts cleanly and serves the UI at the same host/port.
Out of scope for this PR:
- Implementing chat. Just prove the WebSocket pipe is wired.
- Implementing skills config. Just keep the existing endpoints working.
- Rewriting
vibe/api.py's sync wrappers into async. Migrate one by one as endpoints are touched; keep the rest sync and call viarun_in_threadpoolif needed. - Removing the per-loop defensive guards in
OpenCodeServerManager. They become belt-and-suspenders. Drop them in a follow-up PR after the FastAPI substrate has been in production for a release cycle.
Solution
Implementation strategy update after architecture review
The original plan suggested splitting vibe/ui_server.py into many FastAPI
routers immediately. After reviewing the current architecture, that is too
much churn for the first migration PR: it mixes the runtime substrate change
(WSGI/thread-per-request → ASGI/persistent loop) with a large file/module
reshuffle across 70+ routes.
Use a two-step design instead:
- Substrate migration first. Replace Flask/Werkzeug with FastAPI/uvicorn
while keeping
vibe/ui_server.pyas the single route surface. Add a small compatibility layer that supports the limited Flask API the file actually uses (route,before_request,after_request,request,g,jsonify,redirect,send_file,Response, and the existing test helpers). This keeps the first PR focused on runtime semantics and lets existing route handlers move mostly unchanged. - Native FastAPI cleanup second. Once tests and regression are green, convert routes to idiomatic FastAPI incrementally and split them into routers. Router extraction is valuable, but it should be a follow-up because it does not itself fix the cross-event-loop bug.
The compatibility layer must stay intentionally thin and local to the UI server. It is a migration scaffold, not a new app framework. New endpoints after this migration should use native FastAPI patterns directly.
Additional findings from the current codebase:
vibe/ui_server.pyhas one local_run_async()helper that creates a fresh event loop in a thread for WeChat QR login and OpenCode options. This must go away with the Flask migration; FastAPI handlers can await those coroutines directly or call blocking work throughrun_in_threadpool.vibe/api.pystill has sync wrapper functions that callasyncio.run(...)for Telegram auth, SOCKS-backed Discord/Lark calls, OpenCode provider catalog/auth operations, and OAuth web flows. UI-reachable wrappers should be converted as their routes are touched. Test-only or non-UIasyncio.runcalls are not part of this acceptance criterion.- Tests should not be migrated only at the end. Remote-access auth coverage is
split across
tests/test_ui_server_fastapi.pyandtests/ui_server_test_helpers.py; keep those focused tests green after the substrate layer lands, then carry the rest of the UI test files surface by surface. - The current
run_ui_server()tests monkeypatchwerkzeug.make_server. They need to be rewritten arounduvicorn.Serverand the nonblocking remote-access reconcile behavior. - Proxy/remote address semantics are product-critical. The compatibility
request object should preserve the existing
request.remote_addr,request.host, forwarded header, and testenviron_base={"REMOTE_ADDR": ...}behavior before any native Starlette rewrite.
Stack choice
- Web framework: FastAPI (built on Starlette). Native async, first-class WebSocket, dependency-injection, OpenAPI generation, Pydantic body validation.
- Server: uvicorn (single worker — singleton state requires it; multi-worker is wrong for this codebase anyway because the IM controller is in-process).
- Dependencies to add (in
pyproject.toml):fastapi >= 0.110uvicorn[standard] >= 0.27python-multipart >= 0.0.9(for any future form / upload routes)httpx >= 0.27(already a transitive dep; needed explicitly forTestClient)
- Dependencies to remove after tests pass:
flask(transitive via something else? check), explicitwerkzeugreference invibe/runtime.py/vibe/remote_access.pycomments stays as-is.
Module reshape
Keep vibe/ui_server.py as the entry surface for the substrate migration.
After that is stable, split the routes into routers under vibe/ui_routers/
so a 2,380-line file doesn't grow into a 4,000-line file. Suggested split:
vibe/
ui_server.py # app factory, middleware, lifespan, run_ui_server
ui_routers/
__init__.py
health.py # /health, /status
setup.py # /setup/*, /auth/callback (setup wizard)
config.py # /config, /settings, /sessions
backends.py # /backend/*, /agent/*, /cli/detect
backend_oauth.py # /backend/<b>/auth/oauth/*, /backend/opencode/provider/*
backend_codex.py # /backend/codex/auth, /codex/agents, /codex/models
backend_claude.py # /backend/claude/auth, /claude/agents, /claude/models, /backend/claude/api-key/remove
backend_opencode.py # /backend/opencode/providers, /opencode/*
im_platforms.py # /slack/*, /discord/*, /telegram/*, /lark/*, /wechat/*
logs.py # /logs, /version, /upgrade, /doctor, /browse
remote_access.py # /remote-access/*
files.py # SPA catch-all, /assets/*, /favicon, attachments
Routers are wired in ui_server.py via app.include_router(...). Keeps each file under ~400 lines and gives Codex a natural unit of work. This is a follow-up cleanup after the ASGI runtime is live, not a prerequisite for removing Flask.
Translation table (Flask → FastAPI)
| Flask | FastAPI |
|---|---|
@app.route("/x", methods=["POST"]) |
@router.post("/x") |
return jsonify({...}) |
return {...} (FastAPI auto-encodes) |
return jsonify({...}), 400 |
raise HTTPException(status_code=400, detail={...}) or return JSONResponse({...}, status_code=400) |
request.json (sync) |
payload: dict = Body(...) — declare the body param |
request.args.get("x") |
x: str = Query(None) |
request.headers.get("X-Y") |
request: Request then request.headers.get("X-Y") |
request.cookies.get("c") |
c: str = Cookie(None) |
request.remote_addr |
request.client.host (with proxy-header logic in middleware) |
g.something = x (per-request) |
request.state.something = x |
@app.before_request |
@app.middleware("http") async function (see §Middleware) |
@app.after_request |
Same middleware, set response headers / cookies post-await call_next(request) |
Response(status=302, headers={"Location": url}) |
RedirectResponse(url, status_code=302) |
send_file(path, mimetype=...) |
FileResponse(path, media_type=...) |
Response(generator(), mimetype="text/event-stream") |
StreamingResponse(generator(), media_type="text/event-stream") |
werkzeug.exceptions.HTTPException |
fastapi.HTTPException |
make_server(host, port, app).serve_forever() |
uvicorn.run(app, host=host, port=port, log_config=...) |
Middleware: porting before_request / after_request
The Flask app has three security gates run on every request, plus CSRF cookie management. Port each as one async @app.middleware("http") function in ui_server.py. The current Flask hooks are:
- CSRF gate (rejects writes without
X-Vibe-CSRF-Tokenmatching the cookie). Skip for GET/HEAD,/health,/status,/auth/callback,/e2e/simulate-interaction, and loopback-only routes. (Seevibe/ui_server.py:507–530.) - Remote access auth gate (
@app.before_requestat line 905). Decides whether the request is local-loopback or remote, setsg.remote_access_authenticated = bool, redirects unauthenticated remote requests to the vibe-cloud OAuth URL. - Setup wizard gate (
@app.before_requestat line 939). When the setup wizard is incomplete, restricts navigation to/setup/*and a few hard-coded asset paths. - CSRF cookie refresh (
@app.after_requestat line 961). Sets the CSRF cookie if missing. - Remote-access cookie refresh (
@app.after_requestat line 967). Slides the rolling session.
Pattern: one middleware function per concern, ordered explicitly (FastAPI middlewares execute in reverse-registration order on the request, forward order on the response). Use request.state for inter-middleware/route handoff.
The OAuth flow loop: collapse vibe-oauth-loop
vibe/api.py runs a dedicated daemon thread (vibe-oauth-loop) hosting an asyncio loop because Flask handlers can't await directly — every OAuth status read goes through asyncio.run_coroutine_threadsafe(coro, _oauth_loop).result(timeout=...). With FastAPI, the handler is async def and the OAuth service runs on the uvicorn loop natively.
Concretely:
- Delete
_oauth_loop,_oauth_loop_thread,_start_oauth_event_loop(),_submit_oauth_coro()fromvibe/api.py. - Every existing wrapper like:
becomes:def start_oauth_web(backend, ...): service = _get_oauth_service() flow = _submit_oauth_coro(service.start_web_setup(...)) return {...}async def start_oauth_web(backend, ...): service = _get_oauth_service() flow = await service.start_web_setup(...) return {...} - The FastAPI route awaits the new async function directly.
_get_oauth_service()keeps its module-level singleton, but the lazy initialization no longer needs to start a thread — it can simply hold the service. TheAgentAuthServicestays unchanged.
vibe/api.py async migration: incremental
vibe/api.py is currently a mix of sync functions, sync wrappers around async, and a few async helpers. Don't rewrite the whole file in this PR.
Migration rule:
- If an endpoint's handler used
asyncio.run(coro), convert that endpoint AND the function it called intoasync def(both ends). - If the function does CPU-bound or blocking IO (e.g. subprocess + file IO), keep it sync and call it via
await run_in_threadpool(func, ...)from the async endpoint. FastAPI shipsfastapi.concurrency.run_in_threadpool. - Functions not reachable from a Flask handler currently — leave them alone.
The 9 asyncio.run(...) sites in vibe/api.py are the hit list. After migration there should be zero.
Server lifecycle
Replace werkzeug.make_server + serve_forever() with uvicorn:
def run_ui_server(host: str, port: int) -> None:
import uvicorn
paths.ensure_data_dirs()
config = _load_config_safely()
if config is not None:
_start_remote_access_heartbeat_safely(config)
uvicorn_config = uvicorn.Config(
app=app,
host=host,
port=port,
log_config=None, # let our logging.py handle it
access_log=False, # we already log via our own access middleware if needed
loop="asyncio",
lifespan="on",
)
server = uvicorn.Server(uvicorn_config)
_server = server
# Background remote_access reconcile thread stays as-is
threading.Thread(target=_reconcile_remote_access_for_ui_start, args=(config,), daemon=True).start()
server.run() # blocks
Use FastAPI's lifespan context to start / stop the OAuth service singleton
(replacing the daemon-thread loop):
from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app: FastAPI):
# startup
_init_oauth_service() # now lives on uvicorn's loop
yield
# shutdown
await _shutdown_oauth_service()
app = FastAPI(lifespan=lifespan)
Port-bind retry loop (currently in make_server wrapper for EADDRINUSE handling) lives outside uvicorn — wrap server.run() in the same retry loop.
Optional error telemetry
The former external error-reporting integration is intentionally out of scope for this migration. The current product has no external telemetry dependency, initialization, or environment configuration; do not add one back while finishing the remaining FastAPI work.
Tests
Tests use app.test_client() (Flask) extensively. Port pattern:
| Flask test | FastAPI test |
|---|---|
client = app.test_client() |
client = TestClient(app) from fastapi.testclient |
client.post("/x", json={...}) |
client.post("/x", json={...}) (identical API!) |
client.set_cookie(name, value, domain=...) |
client.cookies.set(name, value, domain=...) |
response.get_json() |
response.json() |
response.status_code |
response.status_code |
TestClient is a thin sync wrapper around httpx.Client; it transparently runs the ASGI app under the hood. Most assertions stay byte-identical. Async fixtures (if any) switch to pytest-asyncio patterns.
The historical remote-access auth suite was later split into focused FastAPI
tests; patches like monkeypatch.setattr("vibe.ui_server.psutil...", ...) still
work because the module path is unchanged.
WebSocket smoke route
Prove the substrate by adding one trivial WebSocket route (e.g. /ws/echo) in health.py or a new ws.py:
@router.websocket("/ws/echo")
async def ws_echo(websocket: WebSocket):
await websocket.accept()
try:
while True:
msg = await websocket.receive_text()
await websocket.send_text(f"echo: {msg}")
except WebSocketDisconnect:
pass
The chat feature will land in a follow-up PR using this same pattern. We just need to prove the wiring on this PR.
Risks and mitigations
| Risk | Mitigation |
|---|---|
| 74 routes — long migration, easy to miss subtle response-shape differences | Migrate one router file at a time, run the existing test for that surface after each, smoke via curl. Don't merge until ALL test files pass and a manual smoke against the React UI is clean. |
| Tests embedded in Flask test client semantics (cookies, sessions) | TestClient is largely API-compatible; deal with cookie domain quirks one test file at a time. Allocate ~25% of the migration budget for tests. |
| CSRF / remote_access middleware: ordering bugs | Port one middleware at a time with focused FastAPI tests in tests/test_ui_server_fastapi.py. |
| Optional error telemetry | Out of scope; failures remain in local structured logs. |
WSGI-specific subprocess launching pattern in run_ui_server |
Uvicorn handles this natively in-process; keep the EADDRINUSE retry loop. |
| Frontend assumptions about specific status codes / response shapes | Don't refactor any payload shape during the migration. Same path, same method, same JSON. |
| Streaming responses (logs tail, OAuth status long-poll) | All current "streaming" looks like polling, not SSE. Confirm during route porting; if any real SSE shows up, convert to StreamingResponse. |
| Multi-worker temptation | uvicorn workers >1 = multiple Python processes = singleton state breaks everything. Stay at workers=1. Document this in run_ui_server and in CLAUDE.md if needed. |
Local install path (uv tool install vibe-remote) |
pyproject.toml already declares vibe as a script entry point. Adding fastapi/uvicorn as deps means a slightly bigger wheel — still well under 5 MB. |
Implementation phases
Each phase ends with a green test run + a manual smoke. Commit between phases.
- Bootstrap. Add fastapi/uvicorn/python-multipart/httpx to
pyproject.toml. Createvibe/ui_routers/directory with empty__init__.py. Create the newapp = FastAPI(lifespan=lifespan)invibe/ui_server.pyALONGSIDE the existing Flaskapp(rename Flask app temporarily, e.g._legacy_flask_app). Wirerun_ui_serverto dispatch to whichever app aVIBE_UI_FRAMEWORK=fastapienv var selects. Implement/healthon FastAPI as the canary route. - Middleware. Port CSRF / remote_access auth / setup wizard gate / CSRF cookie / remote_access cookie hooks as FastAPI middleware. Keep the focused FastAPI auth tests green.
- Static + Setup. Port the SPA catch-all,
/setup/*,/auth/callback, asset routes. The setup wizard is high-traffic; smoke through./scripts/run_regression.shend-to-end after this phase. - Backends + agent CLI lifecycle. Port
/backend/*,/agent/*,/cli/detect. Dropasyncio.runfrom the correspondingvibe/api.pyhelpers as you go. - Backend OAuth + per-provider. Port
/backend/<b>/auth/oauth/*and/backend/opencode/provider/*. Deletevibe-oauth-loopthread;_submit_oauth_corocallers becomeawait. This phase fixes the cross-loop bug at the root. - IM platform credentials. Slack / Discord / Telegram / Feishu / WeChat routes. WeChat QR login long-poll is a candidate for
StreamingResponse(or stays as poll — keep behavior identical). - Config / settings / sessions / logs / version / remote-access / browse. The remaining bulk.
- WebSocket smoke route + frontend hello-world dialog (optional) to prove the substrate.
- Cleanup. Remove
VIBE_UI_FRAMEWORKflag, delete_legacy_flask_app, dropflaskfrompyproject.toml, regenerate lockfile. - Tests. Convert
app.test_client()→TestClient(app). The 5–6 test files using Flask testing patterns need a uniform pass.
Codex review after each phase keeps the surface area manageable.
Acceptance checklist (final PR)
-
pyproject.tomldeclares fastapi + uvicorn + python-multipart + httpx; noflaskdependency. -
vibe/ui_server.pyexports a singleapp: FastAPI. No Flask import anywhere invibe/. -
vibe-oauth-loopthread is gone._submit_oauth_corois gone. -
asyncio.rundoes not appear invibe/api.py. - A trivial WebSocket echo route proves the ASGI substrate end-to-end.
- All 74 existing routes return identical responses for golden inputs. UI in
ui/is byte-identical and works against the new server. -
./scripts/run_regression.shbrings up a healthy container;/healthreturns ok; the React UI loads; setup wizard works; OpenCode provider OAuth flow works without cross-loop errors. -
pytest tests/passes. -
vibe restart && vibe statusworks locally. - Repo guidance is updated to mention FastAPI / uvicorn and prefer native FastAPI patterns for new UI routes.
Rollback plan
The migration is too large to be a single commit. Land it as a stacked PR series (one per phase) or one big PR if Codex prefers. If a release goes out and a critical regression surfaces, the fallback is to revert the merge commit — gh-vX.Y.Zrc* pre-releases of the pre-FastAPI version stay installable via uv tool install --force gh-vX.Y.ZrcN. Document the last pre-migration tag prominently in the PR body.
Open questions for the implementer (Codex)
- Phase granularity — single PR or stacked PRs? Single is simpler to verify; stacked is easier to review. Lean stacked if review burden looks heavy.
request.remote_addrproxy header logic — the Flask path has bespoke handling forX-Forwarded-For/X-Forwarded-Hostto support Cloudflare Tunnel. Verify Starlette'srequest.client.hosthonorsforwardedproperly; if not, port the bespoke logic into middleware that writesrequest.state.client_host.- Logging integration — uvicorn has its own access log format. Decide whether to disable uvicorn's access log (current Flask doesn't have one anyway) or pipe it through
vibe/logging.py. - Test client async helpers — if any test currently uses Flask's
with app.test_request_context()pattern, port tohttpx.AsyncClientfor the async equivalent.