Personal Agents Bridge

A single-owner demonstration of ChatGPT → MCP → Agents API → self-hosted Codex → sandboxed Git worktree → independent review → exact-tree draft PR publication.

ChatGPT invokes six MCP tools through Secure MCP Tunnel. The bridge creates Agents API sessions and connects a local Codex executor. For an allowlisted repository, implementation happens in an isolated Git worktree backed by a task-private Git store. Command networking is disabled; writes are confined to the task worktree and task scratch. Implementation agents cannot push or merge.

A separate session independently reviews bounded controller evidence. Only after a completed PASS can publish_task freeze the task and publish the exact reviewed Git tree through the trusted controller. The human retains the merge decision.

This is a public source demonstration, not a multi-user production service or an official OpenAI project. Repository sandboxes permit broad reads; use a dedicated host/account without unrelated secrets. See SECURITY.md and architecture for the actual guarantees and limits. Publishing this source does not make its private MCP deployment publicly accessible.

Setup

Requires Linux, Node.js 24+, npm, Python 3, Git, flock, and standalone Codex with sandbox -P, exec-server, exec-server forward, and its sandbox runtime. The host must permit the required Linux namespaces and Landlock operations. Publication also requires /usr/bin/gh and controller-accessible GitHub authentication. Dependency versions are pinned in package-lock.json; Codex and the tunnel binary are external prerequisites. Protocol/kernel compatibility must be tested on your host.

npm ci --ignore-scripts
npm test

Tests use fake Agents API sessions, real local kernel sandboxes and local Git remotes. They need namespace creation and local listeners; missing enforcement fails tests rather than silently skipping them. They do not publish to GitHub. If Node reports a missing libatomic.so.1, install your OS compatibility package. run.sh also supports an operator-provided library under the private state directory.

Review .env.example for variable names; the application does not load dotenv files automatically. Supply secrets via the process environment or a private secret manager. Never put credentials in MCP arguments or committed files. Follow TUNNEL.md for the private tunnel, owner confirmation and self-hosted execution setup. Start the production bridge with ./run.sh only under the configured tunnel; its singleton lock prevents two controllers using one store.

Register a separate, explicitly approved repository locally:

node register-repository.mjs example /absolute/path/to/approved-repository

The command pins canonical path and filesystem/Git identity in an owner-only local registry. It rejects this bridge's source repository. Never register the bridge as its own implementation target. MCP callers use only repository_id: "example". No repository registrations or account configuration are shipped with this source.

Related MCP server: sark

Workflow

Tool schemas and contracts describe scope, costs, retries, review and publication. Execution/review uses paid API sessions. Publication accepts only task_id, title, optional body, and draft:true (the default), never arbitrary paths, commands or branches. It verifies unchanged state and commit-tree equality, then pushes only its task branch without force. Deletes, renames, modes, symlinks and binary files retain their Git semantics. Submodules are unsupported. PRs target the registered GitHub repository's default branch; the bridge never merges them.

Commands use codex sandbox -P bridge_task -C <worktree> -- <command> with a trusted pinned profile. File-write RPCs have equivalent sandbox enforcement. The outer exec-server transport retains the network access required by the Agents API. Startup probes and controller attestation must succeed before implementation. Tasks without repository_id retain the legacy disposable-workspace isolation; they do not have the repository command-network guarantee and cannot use publication.

Private runtime data

Default state is under ~/.local/state/personal-agents-bridge/; disposable task workspaces and evidence are under /var/tmp/personal-agents-bridge/. These are portable defaults, not paths to a registered repository. /var/tmp may be cleared by the OS. Preserve required artifacts before cleanup or host replacement.

Task expiry cleans remote resources after 15 minutes while retaining files. Explicit workspace deletion verifies absence; bounded audit/task records survive in controller state. Logs, evidence, databases, registry, tunnel configuration and credentials are private operational data and excluded by .gitignore if copied into this checkout. Ignore rules do not sanitize already-tracked files or history.

npm run test:live is a separate, paid manual integration check. It creates real sessions and must not run alongside the production controller. It is not part of npm test and was not used for public-source preparation.

Status and license

See VERIFICATION.md for local coverage and limitations. Live GitHub publication requires a separate, explicitly authorized acceptance test. Licensed under the Apache License 2.0. Third-party dependencies retain their own licenses.