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

> Learn how Codex remote daemon setup uses per-agent CODEX_HOME and socket path validation with SHA-256 aliases for reliable cross-platform startup. Discover the munder-difflin repository.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.