codex-multi-workspace 0.2.0

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

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

Configure cc-switch

If your cc-switch database is not in the legacy Unix-style location, persist its path once:

codex-ws config set cc-switch-db /path/to/cc-switch.db

Read it back:

codex-ws config get cc-switch-db

Run

codex-ws run \
  --provider OpenAI \
  --workspace my-workspace

You can also pass a manifest path directly:

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

--config-db still overrides the saved cc-switch-db value for one run. Like cc-switch, codex-ws resolves ~ from the OS user home directory instead of trusting the HOME environment variable, which avoids common Windows shell path mismatches.

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.