Credential Socket

The Rensei daemon delivers credentials to each agent process through a two-layer system: a spawn-time snapshot injected directly into the agent's environment, and a persistent unix-domain socket the agent can subscribe to for live rotation updates. This page documents both layers so you can debug credential failures and understand what environment variables agents receive.

Why a Credential Socket?

Agent workareas run with a restricted environment - they cannot inherit the operator's shell environment or read files outside their workarea directory. The daemon bridges this gap:

1. Spawn-time injection - immediately before forking the agent, the daemon resolves the org's current credential snapshot from the platform and merges it into the child's os.Environ.
2. Unix-socket subscription - the daemon also exposes a unix socket. The agent connects at startup, sends a HELLO frame, and receives an INITIAL snapshot followed by UPDATE frames whenever a credential rotates.

This dual path means agents always start with credentials pre-loaded and can handle mid-session rotations without restarts.

Socket Path

The daemon sets RENSEI_CREDENTIAL_SOCKET in every agent's environment to the resolved socket path. Agents use this value to connect; never hard-code the path.

# Inside an agent process - connect using the env var
echo $RENSEI_CREDENTIAL_SOCKET
# /tmp/rensei-credentials-501.sock

The socket file is created with mode 0600 and the parent directory with mode 0700 so only the daemon owner can connect.

Wire Protocol

The protocol is line-delimited JSON over a single TCP/unix connection per agent session. Each JSON object is terminated with a newline (\n). The sequence is:

Agent → Daemon   HELLO
Daemon → Agent   INITIAL
Daemon → Agent   UPDATE  (zero or more, on credential rotation)
Either → Either  BYE     (clean shutdown)

HELLO

Sent by the agent immediately after connecting. Identifies the session whose credentials to subscribe to.

{
  "type": "HELLO",
  "sessionId": "sess_01hq..."
}

sessionId must match RENSEI_CREDENTIAL_SESSION_ID in the agent's environment. An empty or missing sessionId closes the connection.

INITIAL

The daemon's reply to a valid HELLO. Contains the full current credential snapshot for the session.

{
  "type": "INITIAL",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-...",
    "LINEAR_API_KEY": "lin_api_...",
    "GITHUB_TOKEN": "ghp_..."
  }
}

The env map may be empty if no credentials are configured for the org/project, or if the daemon's spawn-time snapshot fetch succeeded and there is nothing new to add.

UPDATE

Pushed by the daemon after INITIAL whenever a credential rotation event is received from the platform's rotate-stream SSE endpoint. Only changed keys are included in delta.

{
  "type": "UPDATE",
  "delta": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-new..."
  },
  "rotatedAt": "2026-06-02T14:30:00Z"
}

Agents should merge delta into their in-memory credential store on every UPDATE frame.

BYE

Either side may send BYE to signal a clean shutdown of the connection.

{ "type": "BYE", "reason": "daemon-shutdown" }

The reason field is optional. When the daemon shuts down it sends BYE to all connected agents before closing the socket.

Environment Variables

The daemon populates three credential-related environment variables for each spawned agent:

RENSEI_CREDENTIAL_SNAPSHOT_FAILED=1 is a soft failure signal. The agent's os.Environ still contains whatever partial credentials the daemon could resolve; the socket path is still available for UPDATE frames.

Credential Blocklist

The daemon enforces a hardcoded blocklist of environment variable names that are never delivered to agent processes, regardless of what the platform's snapshot endpoint returns. This is a defence-in-depth layer applied to both INITIAL snapshots and UPDATE deltas.

Blocked variables (from daemon/credentials/socket.go):

RENSEI_DAEMON_JWT
RENSEI_DAEMON_API_KEY
RENSEI_RUNTIME_JWT
WORKER_API_KEY
AUDIT_HMAC_KEY
M2M_JWT_SECRET
WORKOS_API_KEY
WORKOS_COOKIE_PASSWORD
GEMINI_API_KEY
GOOGLE_API_KEY
OPENAI_API_KEY

Spawn-time Injection

Before starting each agent process, the daemon's OnPreSpawn hook calls the platform's /api/daemon/credentials/snapshot endpoint with the session's orgId, projectId, envName, and sessionId. The resolved credentials are merged into the child's exec.Cmd.Env slice before cmd.Start().

This means agent processes receive their credentials in os.Environ() from the moment they start - no socket connection required for the initial set. The socket's INITIAL reply is a defence-in-depth fallback for cases where the spawn-time resolve fails.

Failure modes

None of these failures block the daemon from starting or running sessions. Failures are logged at WARN level in ~/.rensei/daemon.log and ~/Library/Logs/rensei/daemon-error.log (macOS).

Debugging Credential Issues

Step 1 - Check daemon logs for plumbing errors:

rensei host logs -n 100 | grep -i credentials
# or
grep -i credentials ~/Library/Logs/rensei/daemon-error.log

Look for lines like:

[daemon] warning: credential resolver init failed: open ~/.rensei/daemon.jwt: no such file
credentials: spawn-time snapshot failed (fail-open)

Step 2 - Verify the daemon has a valid JWT:

ls -la ~/.rensei/daemon.jwt

If missing, run rensei host install to mint a new install token. The JWT is wiped and re-provisioned automatically.

Step 3 - Verify the socket exists while the daemon is running:

ls -la $RENSEI_CREDENTIAL_SOCKET
# or find it explicitly
ls -la /tmp/rensei-credentials-$(id -u).sock

Step 4 - Manually probe the socket:

# Requires Python 3 or socat
python3 - <<'EOF'
import socket, json, os, sys

sock_path = os.environ.get("RENSEI_CREDENTIAL_SOCKET", f"/tmp/rensei-credentials-{os.getuid()}.sock")
sess_id = os.environ.get("RENSEI_CREDENTIAL_SESSION_ID", "test-session-id")

s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(sock_path)
s.sendall((json.dumps({"type": "HELLO", "sessionId": sess_id}) + "\n").encode())
line = s.makefile().readline()
print(json.dumps(json.loads(line), indent=2))
s.close()
EOF

A healthy socket returns an INITIAL frame. An error connecting means the daemon is not running or the socket path is wrong.

Step 5 - Check platform credential configuration:

If the INITIAL frame has an empty env map, the org has no credentials configured for the active project or environment. Add credentials via the Rensei platform UI under Project → Credentials.

Security Properties

• Socket file mode 0600, parent directory mode 0700 - only the daemon owner can connect.
• Blocklist is enforced on emission, not only at the platform boundary.
• RENSEI_CREDENTIAL_SESSION_ID is per-session only - never set in BaseEnv - so a compromised agent cannot use another session's credential subscription.
• The daemon's JWT (RENSEI_DAEMON_JWT) is blocklisted and never reachable by any agent process.

Related Pages

• Daemon - Install and manage the daemon; log file paths
• Credentials Overview - Platform-side credential provider families and dispatch adapter
• Env Vars Reference - Full list of env vars, including the credential-related blocklist