Skip to content

Runtime Model

Jump to bottom
comfuture edited this page Aug 10, 2026 · 1 revision

Runtime Model

  • Each Codori server instance selects at most one active Codex app-server backend.
  • On macOS and Linux, Codori first probes $CODEX_HOME/app-server-control/app-server-control.sock, where CODEX_HOME defaults to ~/.codex. The probe performs a bounded WebSocket-over-Unix handshake and app-server initialize; the presence of a socket file alone is not enough.
  • If the socket is not ready, Codori runs the bundled codex remote-control start --json once for concurrent requests and probes the socket returned by that command. Unsupported commands, permissions, handshake failures, and incompatible realtime capabilities safely fall back to the Codori-managed TCP app-server.
  • Codori connects to the daemon socket only as a WebSocket client; it never binds, removes, or claims ownership of the socket. Independent clients such as a Codex Desktop SSH proxy and Codori can share one daemon.
  • Codori does not record the daemon PID or directly reap, restart, or stop the daemon. When no ready socket can be reused, however, codex remote-control start may restart a managed app-server if it needs to change the persisted remote-control setting.
  • Each browser bridge gets an independent WebSocket-over-Unix connection. Text and binary app-server frames are forwarded without changing their payloads. A daemon disconnect closes the current browser bridge; the next connection selects a backend again instead of migrating an active JSON-RPC session.
  • The fallback preserves the existing PID/runtime-file and idle-shutdown lifecycle under ~/.codori/run/. Projects and projectless chats remain logical workspaces sharing the selected backend.
  • If an existing managed fallback cannot be stopped safely, Codori keeps its runtime record and continues using it instead of orphaning that process or selecting a second backend.
  • Settings → Backend and GET /api/runtime/backend report the safe backend kind, transport, readiness, version, fallback reason, and resolved Codex executable with its source (override, path, or bundle). The daemon socket path is never exposed to the browser.

Platform limits

The daemon path is Unix-only. The Codori service user must have permission to traverse CODEX_HOME and open the socket. Containerized Codori deployments must mount the same Codex state directory at the effective CODEX_HOME and use compatible UID/GID permissions; otherwise Codori uses the managed fallback. Codori does not relay or translate the remote-control protocol across a container or network boundary.

Workspace lifecycle

  • Stopping the final active workspace stops the managed fallback immediately unless a proxied WebSocket session is still open. It only releases Codori's reference to a first-party daemon.
  • Workspaces with an active proxied WebSocket session keep the managed fallback from being reaped as idle.
  • If a fallback PID/runtime file is stale, Codori cleans it up and starts a fresh managed runtime.

This keeps the browser UI stateless with respect to process ownership while preserving workspace context through explicit Codex app-server cwd parameters.

Server avatar RPC extension

Codori reserves the codori/avatar/* JSON-RPC namespace on its WebSocket proxy. The client uses read, sprites, watch, and unwatch; avatar changes are published as codori/avatar/changed. These messages are consumed by Codori and are not forwarded to Codex app-server. Standard app-server messages, malformed text frames, and binary frames continue through the shared proxy unchanged.

Avatar manifests and spritesheets are size-bounded, image dimensions and animation frames are validated, custom paths must remain within their pet directory, and built-in downloads are restricted to the Codex pet CDN. Invalid or missing selections use a small built-in fallback avatar rather than breaking the RPC connection.

What Codori does

  • Scans a configured root directory and finds descendant directories that contain a direct .git child.
  • Exposes CLI commands to list, start, stop, and inspect logical project workspace runtimes.
  • Prefers the first-party Codex remote-control daemon over a managed fallback.
  • Starts at most one managed app-server fallback on demand and allocates it a free TCP port from a configured safe range.
  • Stores metadata only for the managed fallback under ~/.codori/run/.
  • Provides a dashboard for project selection, chat, and thread resume.
  • Provides bounded, read-only workspace file navigation and local file preview.
  • Proxies browser WebSocket traffic for each project or chat workspace to the shared app-server.
  • Serves the built dashboard bundle from the same origin as the management API.
  • Automatically configures private, loopback-backed Tailscale Serve HTTPS for eligible direct and registered-service launches.

What Codori does not do

Codori v1 does not provide:

  • a general tunnel/provider abstraction
  • public ingress
  • built-in authentication
  • SSO
  • multi-root project indexing
  • a separate Codori-owned thread database
  • file create, edit, rename, move, or delete operations

If you want to access Codori from another machine, you must still provide the private network itself. --tailscale-serve can configure HTTPS only after the host is already connected to Tailscale.

Clone this wiki locally