Codex Remote Exec

Windows-first remote execution fabric for Codex.

Codex stays the brain. This project gives it controlled remote hands: an MCP server exposes tools such as run_powershell, read_file, list_processes, and screenshot; a relay forwards those jobs to an enrolled Windows Agent; the agent executes the job and streams the result back for Codex to decide the next step.

What It Builds

Codex -> MCP server -> public/LAN relay -> Windows Agent -> PowerShell/CMD/files/process/screenshot

apps/mcp-server: stdio MCP server for Codex.
apps/relay: Fastify HTTP API + WebSocket relay + SQLite audit store.
apps/windows-agent: .NET 8 Windows endpoint agent.
packages/protocol: shared TypeScript protocol schemas.

The relay supports both public deployment and LAN deployment. In both modes the Windows Agent makes an outbound WebSocket connection, so the Windows machine does not need an inbound public port.

Security Boundary

This is for devices you own or are explicitly authorized to operate. It is not a hidden agent, evasion tool, or persistence mechanism.

The MVP is intentionally lab-aggressive: once a device is paired and the MCP server is authenticated, Codex can run arbitrary PowerShell on that device. The guardrails are pairing, device tokens, relay auth, job expiry, and durable audit logs.

Quickstart

Use Node.js 24+ and pnpm 11+ for the TypeScript services. Use .NET 8 SDK on Windows for the agent.

1. Start The Relay

cp .env.example .env
# edit RELAY_ADMIN_TOKEN and MCP_AUTH_TOKEN to the same long random value
pnpm install
pnpm build
pnpm dev:relay

For a VPS or public host:

docker compose up --build -d

2. Create A Pairing Code

curl -X POST http://localhost:8787/pairing-codes \
  -H "Authorization: Bearer $RELAY_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresInSeconds":300}'

3. Enroll A Windows Machine

On Windows:

dotnet publish .\apps\windows-agent\src\CodexRemoteExec.Agent\CodexRemoteExec.Agent.csproj -c Release -r win-x64 --self-contained false
.\apps\windows-agent\src\CodexRemoteExec.Agent\bin\Release\net8.0-windows\win-x64\publish\agent.exe enroll --relay http://YOUR_RELAY:8787 --pairing-code ABC12345
.\apps\windows-agent\src\CodexRemoteExec.Agent\bin\Release\net8.0-windows\win-x64\publish\agent.exe run

4. Connect Codex To The MCP Server

Build locally:

pnpm --filter @codex-remote-exec/mcp-server build

Add an MCP server entry in your Codex config:

{
  "mcpServers": {
    "codex-remote-exec": {
      "command": "node",
      "args": ["/absolute/path/to/codex-remote-exec/apps/mcp-server/dist/index.js"],
      "env": {
        "RELAY_URL": "http://YOUR_RELAY:8787",
        "MCP_AUTH_TOKEN": "same-token-as-relay"
      }
    }
  }
}

Codex can then call:

list_devices()
run_powershell(device_id, "ipconfig", 30)
get_system_info(device_id)
read_file(device_id, "C:\\Windows\\System32\\drivers\\etc\\hosts")

MVP Tool Surface

list_devices
run_powershell
run_cmd
get_system_info
read_file / write_file
upload_file / download_file
list_processes
start_process
kill_process
screenshot
create_job / wait_job / cancel_job

Development

pnpm install
pnpm check
pnpm test
pnpm build

Windows Agent tests run on Windows:

dotnet test .\apps\windows-agent\CodexRemoteExec.Agent.sln

Status

This is a working MVP skeleton, not a hardened fleet-management product. The next serious additions are Windows Service install/uninstall, signed job policies, per-tool allowlists, remote terminal streaming, GUI automation, and artifact chunking for large files.

codex-remote-exec