# 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

```text
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

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

```bash
docker compose up --build -d
```

### 2. Create A Pairing Code

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

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

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

Add an MCP server entry in your Codex config:

```json
{
  "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:

```text
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

```bash
pnpm install
pnpm check
pnpm test
pnpm build
```

Windows Agent tests run on Windows:

```powershell
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.