Kowdex

Remote management for Codex instances. Control your local Codex AI assistant from any web browser or mobile device.

What is Kowdex?

Kowdex lets you interact with Codex running on your computer from anywhere. Start conversations, manage multiple instances, and get real-time streaming responses through a modern web interface.

Prerequisites

• Bun runtime installed
• Codex installed and available in your PATH
• mkcert for local TLS certificates

Quick Start

1. Install dependencies

bun install

2. Generate TLS certificates

mkcert -install
mkcert -cert-file certs/localhost+2.pem -key-file certs/localhost+2-key.pem localhost 127.0.0.1 ::1

3. Create configuration

Create a .env file in the project root:

# Server
PORT=4000
HOST=localhost
TLS_ENABLED=true
TLS_CERT=./certs/localhost+2.pem
TLS_KEY=./certs/localhost+2-key.pem

# Authentication tokens (generate your own)
AGENT_TOKEN=your-agent-token-here
CLIENT_TOKEN=your-client-token-here

# Agent
RELAY_URL=wss://localhost:4000/ws

Generate secure tokens:

openssl rand -hex 32

4. Start the services

Open three terminal windows:

Terminal 1 - Relay Server:

bun run dev:relay

Terminal 2 - Web Interface:

bun run dev:web

Terminal 3 - Local Agent:

bun run dev:agent

5. Open the web interface

Navigate to https://localhost:4001 in your browser.

1. Enter your Client Token (the CLIENT_TOKEN from your .env)
2. Enter the Relay URL (wss://localhost:4000/ws)
3. Click Connect

Architecture

Kowdex consists of three components that work together:

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Web App   │ ◄─────► │    Relay    │ ◄─────► │    Agent    │
│  (browser)  │   WSS   │   (server)  │   WSS   │   (local)   │
└─────────────┘         └─────────────┘         └─────────────┘
                                                       │
                                                       ▼
                                                ┌─────────────┐
                                                │    Codex    │
                                                │  (process)  │
                                                └─────────────┘

Web App (packages/web)

The browser-based interface that users interact with. It connects to the relay server via WebSocket and provides:

• Instance management (create, stop, view status)
• Thread management (start, resume, archive conversations)
• Real-time chat with streaming responses
• Approval handling for Codex tool calls

The web app can run on any device with a browser - your phone, tablet, or another computer.

Relay (packages/relay)

The central hub that bridges web clients and agents. It:

• Authenticates connections using separate tokens for agents and clients
• Routes messages between web clients and agents
• Broadcasts events (streaming text, status changes) to connected clients
• Handles multiple concurrent agent and client connections

The relay runs on a server accessible from both the agent and web clients (can be localhost for local development, or a VPS for remote access).

Agent (packages/agent)

Runs on the machine where you want Codex to operate. It:

• Connects to the relay server and authenticates as an agent
• Spawns and manages Codex processes (one per instance)
• Translates relay commands into Codex CLI interactions
• Streams events (responses, tool calls, status) back through the relay

The agent must run on a machine with Codex installed and access to the directories you want to work with.

Communication Flow

1. User sends message → Web App sends turn/start to Relay
2. Relay forwards → Agent receives command, sends to Codex process
3. Codex responds → Agent emits events, Relay broadcasts to Web App
4. Streaming display → Web App renders text as it arrives

All communication uses WebSocket with JSON messages. The relay acts purely as a router - it doesn't store conversations or process commands.

Usage

Creating an Instance

1. Click New Instance on the main page
2. Enter a name and working directory for your Codex instance
3. Click Create

Starting a Conversation

1. Select an instance from the list
2. Click New Thread to start a conversation
3. Type your message and press Enter
4. Watch the streaming response appear in real-time

Managing Instances

• Stop: Click the stop button next to any running instance
• View Threads: Click an instance to see all conversation threads
• Resume: Click any previous thread to continue the conversation

Troubleshooting

Certificate errors in browser

Make sure you ran mkcert -install to trust the local CA. You may need to restart your browser.

Agent not connecting

• Verify AGENT_TOKEN matches in both .env and the agent's environment
• Check that the relay server is running on the expected port
• Look for connection errors in the agent terminal

Codex not starting

• Ensure codex is installed and available in your PATH
• Try running codex --version to verify installation

License

MIT