Archcar Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The Archcar Protocol is a communication framework and sidecar system designed to manage and interact with coding agent sessions (such as Codex or Claude) through pseudo-terminals (PTYs). It facilitates a decoupled architecture where a client (typically the GTK application) can request session lifecycle actions, send input, and receive structured events or screen updates from active agent processes.
The protocol operates over Unix domain sockets using a JSON-RPC-like structure, allowing for idempotent requests, persistent subscriptions to session events, and robust session recovery. It ensures that long-running agent processes remain stable even if the primary GUI front-end is restarted or reconnected.
Sources: crates/core/src/archcar/protocol.rs, crates/core/src/archcar/server.rs:69-80, crates/core/src/archcar/client.rs:24-40
Architecture Overview
The system follows a client-server model utilizing a sidecar binary (archcar). The server manages the actual PTY sessions, while the client handles the user interface and high-level orchestration.
Components
- Archcar Server: A long-running process that binds to a Unix socket. It maintains
ServerState, which includes active session handles, subscriber lists, and queues for pending session spawns. - Archcar Client: Provides a high-level API to send requests and subscribe to events. It includes logic for spawning the sidecar if it is not already running.
- Managed Sessions: Processes run within PTYs. The protocol allows the server to "adopt" existing sessions or restore them from persistent SQLite storage on startup.
The diagram above illustrates the relationship between the GTK application and the Archcar sidecar process.
Sources: crates/core/src/archcar/server.rs:21-31, crates/core/src/archcar/client.rs:136-160, crates/core/src/archcar/session.rs:107-133
Communication Protocol
The protocol uses a structured envelope for all messages sent over the Unix socket.
RpcEnvelope
Every request, response, and event is wrapped in an RpcEnvelope to provide a unique identifier for tracking.
| Field | Type | Description |
|---|---|---|
id | String | A unique UUID v4 generated for each transaction. |
payload | T | The actual request, response, or event data. |
Sources: crates/core/src/archcar/protocol.rs:7-10, crates/core/src/archcar/client.rs:56-60
Request and Response Flow
Most requests are idempotent or trigger asynchronous actions that later broadcast events to all subscribers.
The sequence above shows the typical flow for sending user input to an agent session.
Sources: crates/core/src/archcar/server.rs:113-149, crates/core/src/archcar/protocol.rs:102-110
Request Types
The protocol supports several specialized requests for managing agent lifecycles.
| Request Type | Parameters | Purpose |
|---|---|---|
EnsureWorkspaceDefaultSession | workspace, kind, harness | Ensures a session of a specific kind is running for the workspace, spawning it if necessary. |
EnsureChatThreadSession | workspace, thread_id, kind, harness | Scopes the session to a specific chat thread to maintain conversation continuity. |
SpawnSession | workspace, kind, harness | Explicitly spawns a new session. |
SendInput | session_id, input, kind | Sends user, review, or control text to the PTY. |
ResizeSession | session_id, rows, cols | Adjusts the PTY dimensions for correct TUI rendering. |
KillSession | session_id | Forcefully terminates a session. |
Subscribe | None | Upgrades the connection to a persistent event stream. |
Sources: crates/core/src/archcar/protocol.rs:21-61
Event Broadcast System
The Archcar Server maintains a list of subscribers and broadcasts state changes as ArchcarEvent payloads. This allows the GUI to update in real-time without constant polling.
Key Events
- SessionStarted: Triggered when a PTY is successfully spawned or adopted.
- SessionReady: Emitted when the harness controller detects the agent is ready for input (e.g., Codex finished booting).
- SessionScreenUpdated: Fired whenever the visible screen text of the PTY changes.
- SessionMessagesUpdated: Indicates that new structured messages (user/agent turns) have been parsed from the screen.
- SessionExited: Sent when the underlying process terminates.
Sources: crates/core/src/archcar/protocol.rs:212-243, crates/core/src/archcar/session.rs:360-400
Session Management and Persistence
A core feature of the protocol is the ability to maintain sessions across sidecar restarts.
Reconciliation on Startup
When the ArchcarServer starts, it performs a reconciliation pass:
- It queries the SQLite
WorkspaceStorefor all sessions marked asRunning. - It checks if the process PID is still alive.
- If the process is dead, it marks the session as
Exitedin the database. - If it is alive and belongs to the Archcar logs directory, it becomes a candidate for adoption.
Sources: crates/core/src/archcar/server.rs:33-47, crates/core/src/archcar/session.rs:247-285
Managed Session Connection Logic
Sessions can be in one of two states internally:
- Live: Directly controlled via an active
PtySessionobject. - Reattached: Reconnected to an existing PTY slave via
/proc/{pid}/fd/0.
This logic ensures that agent work is not lost if the UI or sidecar process crashes.
Sources: crates/core/src/archcar/session.rs:46-105, crates/core/src/archcar/server.rs:430-475
Security and Redaction
The protocol includes built-in safeguards for sensitive information. Both the client and server log RPC summaries rather than full payloads by default.
Redaction Logic
When logging is enabled for full payloads (via ARCHDUCTOR_LOG_ARCHCAR_PAYLOADS), the system passes raw text through redaction filters to hide:
- OpenAI API Keys (
sk-...) - GitHub Personal Access Tokens (
ghp_...) - Passwords and other sensitive bearer tokens.
Sources: crates/core/src/archcar/client.rs:188-212, crates/core/src/archcar/protocol.rs:159-183
Conclusion
The Archcar Protocol provides a robust, asynchronous backbone for managing parallel coding agents. By abstracting PTY management into a sidecar process and utilizing a structured JSON-RPC interface, it enables the Archductor system to provide a seamless, persistent experience for complex AI-driven workflows while maintaining high reliability through session adoption and reattachment.