codex-multi-workspace

Run Codex CLI in Docker with saved single-folder or multi-folder workspaces.

codex-multi-workspace provides the codex-ws command. It reads Codex provider profiles from cc-switch, mounts one or more project folders into a container, and keeps each workspace's Codex sessions under ~/.codex-ws.

Requirements

• Docker
• Rust/Cargo for installation
• A cc-switch database with at least one Codex provider

The default runtime image is published to GHCR and is based on ghcr.io/openai/codex-universal. It includes Codex CLI and uses Codex Universal runtime variables for language versions.

Install

cargo install codex-multi-workspace

Create a Workspace

codex-ws workspace add my-workspace

This creates and opens:

~/.codex-ws/config/workspace/my-workspace.yaml

Example:

name: my-workspace
folders:
  - /absolute/path/to/project

# Optional Codex Universal language runtimes.
# runtime:
#   - node:22
#   - python:3.13

List saved workspaces:

codex-ws workspace ls

Run

codex-ws run \
  --provider OpenAI \
  --workspace my-workspace \
  --config-db ~/.cc-switch/cc-switch.db

You can also pass a manifest path directly:

codex-ws run --provider OpenAI --workspace /path/to/workspace.yaml

Runtime Image

By default, codex-ws uses:

ghcr.io/honahec/codex-multi-workspace:latest

Override it when needed:

codex-ws run --provider OpenAI --workspace my-workspace --image my-codex-runtime:latest

Welcome Stars and PRs.