AgentVault OpenAI Bridge

Connect a local OpenAI Codex login to encrypted AgentVault owner direct messages and rooms. This is the openai framework under the existing harness runtime. It does not use an OpenAI API key or the archived Codex channel runtime.

Release status: initial release. The app offers installation only after registry installation and an owner-authenticated live messaging check pass. Tests alone do not establish account access, billing eligibility, or production delivery.

Prerequisites and login

Node.js 20 or newer, macOS or Linux, and the native Codex CLI 0.154.0 executable on PATH are required. The supported model is fixed to gpt-5.6-terra. A JavaScript npm launcher that requires Node from a Homebrew/custom PATH cannot run inside the deliberately minimal child PATH; install the native Codex executable instead. Other CLI versions fail closed because the disabled-tool boundary must be measured again before upgrading.

Install it globally (npm install -g @agentvault/openai-bridge). Development builds can run node dist/index.js --help; background service installation rejects temporary package-cache entrypoints.

Choose one agent name and use it for every command:

AV_AGENT_NAME=aster agentvault-openai-bridge login
AV_AGENT_NAME=aster agentvault-openai-bridge doctor
AV_AGENT_NAME=aster AV_INVITE_TOKEN='<invite>' agentvault-openai-bridge run

login explicitly runs the official Codex device-auth login. It uses this agent's dedicated auth directory and does not reuse your normal Codex login or configuration. Complete the browser instructions printed by Codex. No login or provider call happens during package installation, help, version, or tests.

The invite remains in a mode-0600 pending-invite file until the encrypted channel becomes ready after approval. A restart loads existing AgentVault credentials. Keep the same AV_AGENT_NAME; another name selects separate auth, device credentials and history.

Background service

After explicit login and global installation:

AV_AGENT_NAME=aster AV_INVITE_TOKEN='<invite>' agentvault-openai-bridge install
AV_AGENT_NAME=aster agentvault-openai-bridge status
AV_AGENT_NAME=aster agentvault-openai-bridge logs
AV_AGENT_NAME=aster agentvault-openai-bridge restart
AV_AGENT_NAME=aster agentvault-openai-bridge uninstall

macOS uses a per-user launchd service; Linux uses user systemd. Linux services normally require an active user manager; configure user lingering separately if you need execution after logout. Services use the resolved stable Node and bridge paths, and the saved absolute Codex path. uninstall removes the service definition and retains credentials/history. status reports service-manager state; doctor checks binary compatibility and file presence, without opening credentials or claiming that the account is valid.

If Codex is upgraded, install the supported version again before restarting. If authentication expires, run uninstall, run login again with the same name, then run install again. These commands retain the agent credentials and history. For replacement enrollment, stop the existing service with uninstall, obtain a fresh recovery invite from the app, then run:

AV_AGENT_NAME=aster AV_INVITE_TOKEN='<fresh-invite>' agentvault-openai-bridge replace

Replacement acquires the agent lock before archiving prior AgentVault credentials under the private replacement-recovery/<uuid>/ directory and forcing enrollment. Codex login and history are retained. Existing credentials are never silently reused for this explicit command. If enrollment fails, the archive remains for deliberate operator recovery; normal restarts do not restore it automatically. After approval, stop the foreground process and install the service again. Do not copy another agent's credentials into this state directory.

The shared SecureChannel currently persists new enrollment keys only after activation. A crash before approval can leave the invite consumed without recoverable local keys. Retaining pending-invite does not solve that gap: obtain a fresh recovery invite if the interrupted enrollment cannot resume.

Conversation and privacy boundaries

Only direct messages positively attested by SecureChannel as owner 1:1 messages can dispatch a private turn. Rooms answer according to AgentVault's shared mention policy, evaluated on the typed caption, and remain silent while hushed. Recent context comes only from the addressed room. Replies are bound to the original conversation ID or room ID. Device ID, conversation kind, and conversation ID jointly select a separate persistent Codex session UUID; the bridge never resumes “last”.

Each agent stores its state beneath ~/.agentvault/openai/<name-slug>/, including isolated home, codex, work, tmp, and sessions directories (0700). Codex auth and local conversation transcripts persist there. Encryption protects AgentVault transport; local Codex history is plaintext and relies on the host account's filesystem protections. Do not share this directory.

Codex children receive only a dedicated HOME, CODEX_HOME, TMPDIR, and a minimal PATH. The measured configuration disables shell, filesystem tools, web search, MCP/apps/plugins, delegation, and other integrations. Read-only sandboxing and approval never are mandatory because an unadvertised patch handler still exists. Built-in Codex system skill descriptions may appear in context, but host user skills/configuration are not inherited. Arbitrary model, provider, environment and tool configuration are intentionally unavailable.

The bridge accepts only a terminal successful assistant reply after exit 0. Because the exec stream omits message phase, it additionally verifies the current turn's final_answer in the bounded local Codex rollout; a prior resumed turn or commentary cannot authorize delivery. Partial, failed, malformed, oversized or timed-out turns are discarded. Disconnect and shutdown invalidate pending results. One bounded queue serializes inference and awaited sending; child process groups are killed and reaped before another turn starts. Logs contain bridge-owned status codes, without prompts, replies, tokens or provider diagnostics.

Local checks

npm test
npm run typecheck
npm run build
node dist/index.js --help
npm pack --dry-run --ignore-scripts

Tests use disposable fixture roots, fake executables, fake encrypted channels, and injected service commands. They never run launchctl/systemctl, log into an account, contact AgentVault, or call a real provider. The build bundles the freshly built local SecureChannel artifact and checks required enrollment/sender fields.

The optional real-binary gate runs only when explicitly invoked after a build:

python3 scripts/mock-provider-gate.py --codex /absolute/path/to/native/codex

It binds a loopback mock provider, asserts an empty tool catalog, denies hostile execution/patching, checks exact-UUID resume, rejects commentary and timeout output, and retains fixture artifacts for inspection. It never logs into an account or reaches a real provider.