Codex Remote Daemon Setup: Per-Agent CODEX_HOME and Socket Path Validation

The Codex remote daemon in chaitanyagiri/munder-difflin launches each agent with an isolated CODEX_HOME and validates socket paths against a 104-byte limit by generating deterministic SHA-256 aliases under /tmp/mdc to ensure reliable cross-platform startup.

The chaitanyagiri/munder-difflin repository manages multiple autonomous agents, each requiring its own Codex configuration directory. Because macOS enforces a strict 104-byte maximum on Unix-domain socket paths, the system cannot use long absolute CODEX_HOME paths directly. Instead, the implementation in src/shared/codexRemote.ts creates compact, unique aliases that guarantee the control socket fits within OS limits while maintaining per-agent isolation.

The macOS Socket Path Constraint

Unix-domain sockets on macOS are limited to 104 bytes (the CODEX_REMOTE_SOCKET_MAX constant). A standard CODEX_HOME path such as /very/long/absolute/path/to/agent/directory/.codex quickly exceeds this limit when combined with the relative socket path app-server-control/app-server-control.sock. To prevent daemon startup failures, every socket path must pass validation via codexRemoteSocketFits(aliasPath) before the daemon launches.

Per-Agent CODEX_HOME Isolation

Each agent receives its own dedicated CODEX_HOME directory (typically named .codex within the agent's working directory). This isolation prevents configuration collisions and allows independent versioning. However, these absolute paths are often too long for socket creation. The solution computes a short alias that maps to the real CODEX_HOME without moving any files.

Generating Short Aliases with SHA-256

The alias generation logic resides in src/shared/codexRemote.ts and follows a deterministic algorithm to ensure consistent paths across process restarts.

Deterministic Digest Calculation

The system computes a SHA-256 hash of the concatenated real CODEX_HOME path and the agent ID, then truncates the result to 8 hexadecimal characters. This produces a compact, unique identifier for each agent:

import { codexRemoteAliasPath } from './src/shared/codexRemote';

const realHome = '/path/to/agent/workspace/.codex';
const agentId = 'dev-1';

const alias = codexRemoteAliasPath(realHome, agentId);
// → "/tmp/mdc/1a2b3c4d"

Alias Root and Path Construction

The alias root is fixed at /tmp/mdc (the tempRoot). The final alias path joins this root with the 8-character digest:

1. Alias root: /tmp/mdc
2. Digest: First 8 chars of SHA-256(realHome + agentId)
3. Full alias: join('/tmp/mdc', digest) → /tmp/mdc/1a2b3c4d

This structure guarantees that the eventual socket path stays well under the 104-byte limit.

Validating Socket Path Lengths

Before spawning the daemon, the code validates that the complete socket path will fit. The function codexRemoteSocketFits checks:

import { codexRemoteSocketFits, CODEX_REMOTE_SOCKET_RELATIVE } from './src/shared/codexRemote';

const aliasPath = '/tmp/mdc/1a2b3c4d';
const fits = codexRemoteSocketFits(aliasPath);

if (!fits) {
  throw new Error('Codex socket path would exceed platform limit');
}

The validation computes join(aliasPath, CODEX_REMOTE_SOCKET_RELATIVE) and verifies the length is less than CODEX_REMOTE_SOCKET_MAX (104). Because the alias uses only 8 characters plus the fixed root, the check always passes for valid configurations.

Launching the Daemon with Validated Endpoints

Once validated, the system constructs the full Unix-socket endpoint and injects it into the Codex CLI arguments.

Constructing the Endpoint

The codexRemoteEndpoint function appends the relative socket path to the alias:

import { codexRemoteEndpoint } from './src/shared/codexRemote';

const endpoint = codexRemoteEndpoint('/tmp/mdc/1a2b3c4d');
// → "unix:///tmp/mdc/1a2b3c4d/app-server-control/app-server-control.sock"

Injecting Remote Arguments

The withCodexRemoteArgs helper prepends the --remote flag to the command line unless one already exists:

import { withCodexRemoteArgs } from './src/shared/codexRemote';

const baseArgs = ['--model', 'gpt-5-codex'];
const args = withCodexRemoteArgs(baseArgs, endpoint);
// → ["--remote","unix:///tmp/mdc/.../app-server-control.sock","--model","gpt-5-codex"]

This ensures every worker process connects to the correct per-agent daemon via the shortened, validated socket path.

Complete Launch Flow

A typical worker launch sequence combines these utilities as implemented in the worker launcher:

import { launch } from './src/shared/workerLauncher';

const worker = launch({
  requestCommand: 'codex',
  autoMode: true,
  agentId: 'dev-1',
  codexHome: '/very/long/path/to/agent/.codex',
});

// Internally executes:
// 1. alias = codexRemoteAliasPath(codexHome, agentId)
// 2. assert(codexRemoteSocketFits(alias))
// 3. endpoint = codexRemoteEndpoint(alias)
// 4. args = withCodexRemoteArgs(commandArgs, endpoint)
// 5. spawn('codex', args)

Summary

• Per-agent isolation: Each agent receives a unique CODEX_HOME directory to prevent configuration conflicts.
• 104-byte limit: macOS restricts Unix-domain socket paths to 104 bytes (CODEX_REMOTE_SOCKET_MAX), necessitating path shortening.
• Deterministic aliases: The system generates 8-character SHA-256 digests under /tmp/mdc to create short, unique paths for each agent.
• Validation: codexRemoteSocketFits verifies the complete socket path length before daemon startup.
• Argument injection: withCodexRemoteArgs automatically prepends the validated --remote unix://... endpoint to Codex CLI invocations.

Frequently Asked Questions

Why does the Codex remote daemon require per-agent CODEX_HOME directories?

Isolating each agent's CODEX_HOME prevents state pollution and allows independent credential storage, model settings, and conversation history. According to the source in src/shared/codexRemote.ts, the daemon creates a control socket inside this directory, so overlapping paths would cause socket collisions and startup failures when multiple agents run concurrently.

What happens if the socket path exceeds 104 bytes on macOS?

The daemon would fail to create the Unix-domain socket, causing the worker launch to fail. The implementation explicitly guards against this via codexRemoteSocketFits, which validates the computed path against CODEX_REMOTE_SOCKET_MAX (104) before spawning the process. If validation fails, the system throws an error before attempting to bind the socket.

How is the alias path deterministic across restarts?

The alias computation in codexRemoteAliasPath uses a SHA-256 hash of the concatenated real CODEX_HOME absolute path and the agent ID, truncated to 8 hexadecimal characters. Because these inputs remain constant for a given agent, the alias path /tmp/mdc/{digest} is identical every time the system restarts, allowing seamless reconnection to existing daemon sockets.

Where is the socket validation logic tested?

The unit tests in test/codex-remote.test.cjs exercise the alias generation, socket-fit validation, and endpoint construction logic. These tests confirm that the digest length remains fixed at 8 characters, that codexRemoteSocketFits correctly identifies paths under the 104-byte limit, and that codexRemoteEndpoint returns properly formatted unix:// URLs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}