Codais

Codais is an independent concept prototype for an Apple-first control surface for Codex-powered agent workflows. It pairs an iPhone, iPad, or Vision Pro client with a trusted Mac companion that owns local files, shells, and Codex CLI execution. A lightweight relay service handles pairing and routing when the client and companion are not on the same local network.

This repository is not an official OpenAI project and is not affiliated with, endorsed by, or maintained by OpenAI. It is intended as an experimental reference implementation for local-first mobile companion workflows.

The project is currently a prototype monorepo for three cooperating apps:

• apple-client: SwiftUI client for iOS, iPadOS, and visionOS.
• mac-companion: Rust/Axum service that exposes a local HTTP and WebSocket API around Codex sessions.
• relay-service: Node.js/TypeScript relay for pairing, token refresh, revocation, and WebSocket forwarding.

What It Does

• Connects Apple devices to a Mac companion through direct LAN URLs or relay pairing.
• Starts, resumes, cancels, and streams Codex-backed sessions.
• Lets the user choose model, reasoning effort, and working directory before starting work.
• Shows session history, tool/log events, and live output in the Apple client.
• Browses and previews files from the configured Mac workspace.
• Keeps execution authority on the Mac; the relay never runs shell or Codex workloads.

Screenshots

Welcome	Connect	Chat	Composer	Files

Repository Layout

.
|-- apple-client/      SwiftUI mobile and visionOS targets
|-- mac-companion/     Rust local companion API and Codex runner bridge
|-- relay-service/     TypeScript relay API and WebSocket router
|-- docs/              Architecture notes
`-- scripts/           Local development helpers

Architecture

Apple Client
  |
  | direct HTTP/WS on LAN
  v
Mac Companion ----------------> Codex CLI + local workspace
  ^
  | relay WebSocket bridge
  v
Relay Service

The preferred local path is direct Apple Client to Mac Companion communication. The relay path exists for pairing and remote routing. See docs/architecture.md for more detail.

Requirements

• macOS with Xcode and iOS/visionOS SDK support
• Rust toolchain for mac-companion
• Node.js 22 or newer for relay-service
• XcodeGen for regenerating apple-client/Codais.xcodeproj
• Codex CLI installed on the Mac when real execution mode is enabled

Quick Start

1. Start the Mac Companion

cd mac-companion
cargo run

Default companion URL:

http://localhost:8787

For real Codex execution, run with:

export CODAIS_ENABLE_REAL_CODEX=1
export COMPANION_WORKSPACE_ROOT=/abs/path/to/workspace
cargo run

Without CODAIS_ENABLE_REAL_CODEX=1, the companion uses simulated session events for local UI development.

2. Start the Relay Service

cd relay-service
npm install
npm run dev

Default relay URL:

http://localhost:8080

3. Open the Apple Client

cd apple-client
xcodegen generate
open Codais.xcodeproj

Available schemes:

• CodaisMobile
• CodaisVision

Configuration

Mac Companion

Variable	Default	Purpose
COMPANION_HOST	0.0.0.0	Bind host for the companion server.
COMPANION_PORT	8787	Bind port for the companion server.
COMPANION_TOKEN	unset	Optional bearer token for companion HTTP and WebSocket endpoints.
COMPANION_WORKSPACE_ROOT	current directory or home fallback	Root directory exposed to file browsing and Codex execution.
COMPANION_CORS_ORIGINS	unset	Comma-separated allowed CORS origins.
CODAIS_ENABLE_REAL_CODEX	unset	Set to 1 to execute the local Codex CLI.
RELAY_BASE_URL	unset	Enables relay bridge when configured.
RELAY_PAIRING_ID	unset	Pairing identifier for relay bridge mode.
RELAY_ACCESS_TOKEN	unset	Access token for relay bridge mode.
RELAY_REFRESH_TOKEN	unset	Refresh token for relay bridge mode.
RUST_LOG	codais_mac_companion=info	Rust tracing filter.

Relay Service

Variable	Default	Purpose
RELAY_PORT	8080	HTTP and WebSocket port.
RELAY_STATE_FILE	relay-service/data/relay-state.json	Persistent pairing state file outside tests.
NODE_ENV	unset	test disables state persistence.

Apple Client

Variable	Purpose
CODAIS_COMPANION_URL	Optional launch environment override for the companion base URL.
CODAIS_RELAY_URL	Optional launch environment override for the relay base URL.

The app also stores selected model, reasoning effort, workspace, and endpoint settings in user defaults.

HTTP and WebSocket APIs

Mac Companion

• GET /health
• GET /capabilities
• GET /files?path=.
• GET /file?path=<relative-path>&max_bytes=65536
• POST /session
• POST /session/{id}/message
• POST /session/{id}/cancel
• GET /session/{id}/history
• WS /session/{id}/stream

Relay Service

• POST /pairing/start
• POST /pairing/confirm
• POST /pairing/refresh
• POST /pairing/revoke
• WS /relay/session/{id}/stream?pairingId=...&role=client|companion&token=...

Development Checks

Run the companion tests:

cd mac-companion
cargo test

Run relay tests:

cd relay-service
npm test

Check relay TypeScript compilation:

cd relay-service
npm run build

List Xcode targets and schemes:

xcodebuild -list -project apple-client/Codais.xcodeproj

Security Model

• Mobile and visionOS clients do not execute shell commands locally.
• The Mac companion is the trust boundary for workspace access and Codex execution.
• The relay stores pairing state and forwards messages but does not execute agent tasks.
• Pairing uses short-lived access tokens plus refresh tokens.
• COMPANION_TOKEN should be set before exposing the companion beyond local development.
• Do not commit .env files, local state files, API keys, bearer tokens, provisioning profiles, or screenshots that expose private workspace names.

Status

Codais is an early-stage concept prototype. The current codebase focuses on pairing, session orchestration, streaming events, workspace file access, and SwiftUI control surfaces for mobile and visionOS clients.

It is not production-ready. Review the security model, set explicit authentication, and test carefully before exposing any companion or relay endpoint beyond local development.

License

Codais is released under the MIT License. See LICENSE for details.

Copyright (c) 2026 Codais contributors.