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.
Windows Controller Control IPC
Status
- Owner: Avibe Controller control IPC
- Scope: the existing internal HTTP routes and SSE streams
- POSIX transport: unchanged Unix-domain socket
- Windows transport: authenticated ephemeral IPv4 loopback TCP
- Contract version: 1
Goal
The Controller and its local UI/CLI child processes need one HTTP transport on native Windows without changing the routes, response bodies, or SSE event ordering that already run over a Unix-domain socket on POSIX.
This contract does not introduce custom HTTP over named pipes. It does not change Runtime process ownership, Tauri lifecycle, terminal, Vault credential IPC, agent backends, Show Runtime, dependency installation, or packaging.
Endpoint Selection
POSIX
POSIX keeps the existing endpoint and behavior:
- default socket:
${AVIBE_HOME}/state/dispatch.sock; - override:
VIBE_INTERNAL_DISPATCH_SOCKET; - transport:
AF_UNIXstream socket; - socket mode: best-effort
0600under a restrictive bind-time umask; - HTTP base URL used by clients:
http://localhost; - no bearer header or endpoint descriptor.
An explicit socket_path passed by an existing caller remains an explicit UDS
endpoint. Existing POSIX callers do not read the Windows descriptor.
Windows
The Controller pre-binds an AF_INET listener to 127.0.0.1:0, calls
listen, and then publishes:
%AVIBE_HOME%\runtime\control-ipc\endpoint.json
AVIBE_HOME retains its existing meaning. The default therefore lives below
the current user's Avibe home, not a machine-wide temporary directory.
The descriptor sits in its own control-ipc directory rather than the runtime
root because the Controller hardens the containing directory, not only the
file. That hardening is only safe where every entry belongs to control IPC.
The UTF-8 JSON descriptor has exactly this version-1 shape:
{
"schema_version": 1,
"transport": "tcp",
"host": "127.0.0.1",
"port": 49152,
"instance_id": "d69b9554dfb64cb6a1ca1df963fb3888",
"bearer_token": "43-or-more-URL-safe-random-characters"
}
| Field | Producer | Consumer | Contract |
|---|---|---|---|
schema_version |
Controller host | internal clients | Integer 1; any other value is unsupported |
transport |
Controller host | internal clients | Literal tcp |
host |
Controller host | internal clients | Literal 127.0.0.1; hostnames, wildcard addresses, and non-loopback addresses are rejected |
port |
bound listener | internal clients | Integer 1..65535; it is read from the pre-bound listener |
instance_id |
Controller host | server middleware and internal clients | 128-bit random lowercase hexadecimal identifier |
bearer_token |
Controller host | server middleware and internal clients | At least 256 bits from the OS CSPRNG, encoded as URL-safe text |
Unknown top-level fields are rejected in version 1. The descriptor is a local secret because it contains the bearer token.
The Controller creates the runtime directory, lock file, temporary descriptor, and stable descriptor with explicit private security:
- POSIX uses
0700for the directory and0600for files; - Windows uses a protected, non-inherited DACL with full access granted only to the current user SID and Local System, and records the current user SID as owner.
Windows creation passes this security descriptor to CreateDirectoryW and
CreateFileW; it does not expose an inherited-permission file and tighten it
afterward. Before consuming a descriptor, the client validates the opened
file's owner and exact protected DACL. A descriptor, lock, or runtime directory
with a different owner, an inherited DACL, or any additional allow entry is
rejected. A producer may tighten an existing current-user-owned artifact during
publication for upgrade compatibility, but it never changes or accepts an
artifact owned by another principal. Windows security API failures fail startup
or discovery closed.
Descriptor contents, authorization headers, and bearer tokens must not appear in logs, exceptions, HTTP response bodies, or test failure output.
Producer And Consumer Ownership
The Controller-side ControlIpcHost owns:
- transport selection;
- listener creation and pre-bind;
- instance ID and bearer generation;
- atomic descriptor publication;
- request authentication and instance response headers on Windows;
- owner-safe endpoint cleanup.
vibe.internal_client owns:
- platform-specific endpoint discovery;
- strict descriptor parsing;
- attaching authentication to every Windows request and stream;
- checking the responding instance on every Windows response and stream;
- translating discovery, connect, authentication, and stale-instance failures into the existing unavailable/timeout behavior.
The UI-process Model Hub RPC client uses this same endpoint discovery,
transport, bearer header, and instance-response validation contract. It does
not inspect dispatch.sock or construct a UDS transport independently.
Any internal caller that opens dispatch.sock directly instead of using the
shared client connection contract remains POSIX-only until its owning lane
migrates it. The Windows server never provides an unauthenticated compatibility
path for such callers.
Authentication And Instance Binding
Every Windows request, including GET /internal/health, both SSE routes, and
all mutating routes, carries:
Authorization: Bearer <bearer_token>
The server compares the credential in constant time. Missing, malformed, or
incorrect credentials receive a generic 401 response. The response does not
echo the credential or explain which part failed.
Every authenticated Windows response carries:
X-Avibe-Control-Instance: <instance_id>
This includes framework-generated 500 Internal Server Error responses for
unhandled route exceptions. The Windows-only error handler preserves the
framework's status and plain-text body while adding the instance header.
The client compares that value with the descriptor's instance_id before it
accepts a response or consumes an SSE body. A missing or mismatched header is a
stale-instance failure. This prevents a stale descriptor from silently
connecting to an unrelated listener or a successor Controller that reused the
same port.
POSIX remains authenticated by possession and filesystem permissions of the Unix socket and does not require these HTTP headers.
Descriptor Validation
A Windows client rejects the descriptor before opening a connection when any of the following is true:
- the path is absent, a symlink, not a regular file, unreadable, or larger than the bounded descriptor size;
- JSON is malformed, is not an object, has missing or unknown fields, or uses the wrong primitive types;
schema_versionortransportis unsupported;hostis not exactly127.0.0.1;portis outside1..65535;instance_idis not the version-1 128-bit hexadecimal form;bearer_tokenis not the version-1 URL-safe minimum-strength form.
Errors identify only the descriptor category and path. They never include raw descriptor data.
Startup And Atomic Publication
Windows startup is ordered:
- create the runtime directory and user-only lock file;
- create a fresh instance ID and bearer token;
- create a fresh TCP socket;
- enable exclusive-address semantics where Windows supports them;
- bind to
127.0.0.1:0, calllisten, and set non-blocking mode; - read the assigned port from
getsockname; - write and
fsynca user-only temporary descriptor in the control IPC directory; - while holding the descriptor lock, atomically replace
endpoint.json; - hand the already-bound listener to uvicorn.
The stable descriptor never contains an unbound or requested port. Bind failure publishes nothing. Publication failure closes the listener and leaves the previous stable descriptor untouched.
An EADDRINUSE result while binding the ephemeral listener is retried with a
fresh socket up to three total bind attempts. Other bind errors fail startup
immediately. The OS still selects every candidate port; Avibe does not scan or
persist a preferred port.
Shutdown And Stale Instances
Graceful shutdown first stops the server task and closes its listener. The
Windows host then acquires the same descriptor lock used by publication,
re-reads the stable descriptor, and removes it only when both instance_id and
bearer_token match the current host.
A stale Controller whose descriptor has already been atomically replaced by a successor therefore leaves the successor descriptor untouched. Missing, malformed, or non-owned descriptors are also left untouched.
A hard crash can leave a descriptor behind. Clients treat connect failure, authentication failure, or instance-header mismatch as unavailable. A successor binds a fresh listener and atomically replaces the stale descriptor after bind succeeds. Each new host instance generates a new instance ID and bearer credential; neither credential is reused across a successor publication.
POSIX keeps its existing stale socket replacement on startup and socket unlink on graceful server shutdown.
Retry And Reconnect
- Listener bind: only
EADDRINUSE, at most three total attempts, always with a fresh socket. - Descriptor publication: one atomic replace attempt while locked; a failure is a startup failure and does not publish partial JSON.
- Ordinary request: no hidden application-level retry. The existing caller decides whether unavailable/timeout is retryable.
- SSE connection: one descriptor snapshot per connection. The client does not switch instances inside a live stream.
- SSE reconnect: the existing subscriber reconnect loop calls the client again; that new call re-reads the descriptor, re-authenticates, and validates the new instance header.
This avoids replaying mutating requests while allowing a long-lived SSE consumer to follow a restarted Controller safely.
HTTP And SSE Compatibility
Windows exposes the same FastAPI application, methods, paths, status codes, JSON bodies, and SSE payloads as POSIX. Authentication is transport middleware, not route logic.
For both POST /internal/dispatch and GET /internal/events:
- uvicorn receives the pre-bound listener;
- SSE framing remains
event:followed by JSONdata:and one blank line; - non-ASCII JSON content remains UTF-8 end to end;
- event order is unchanged;
- authentication and instance validation complete before the client consumes the first SSE event;
- a disconnect does not replay or reorder events; the existing route/caller semantics decide what a new request observes.
Verification Contract
Focused automated evidence must cover:
- unchanged POSIX UDS selection and explicit UDS override;
- Windows TCP descriptor selection and strict validation;
- Windows current-user/SYSTEM-only owner and DACL enforcement for the runtime directory, lock, temporary descriptor, and stable descriptor;
- rejection of widened or non-owner Windows artifacts, plus upgrade-time repair only for current-user-owned artifacts;
- real loopback HTTP/SSE with non-ASCII dispatch data and preserved event order;
- missing and incorrect bearer rejection;
- stale descriptor and mismatched instance rejection;
- Model Hub sync and async RPCs through the shared Windows endpoint, bearer, and instance validation;
- instance headers on authenticated framework-generated 500 responses;
- atomic descriptor replacement without partial reads;
- owner-safe cleanup after successor replacement;
- occupied-port rebind behavior with a fresh socket;
- SSE reconnect through a successor descriptor;
- Ruff on every changed Python file.
A focused windows-latest CI job is required until an existing Windows job
installs the test dependencies and exercises this contract.