codex-multi-workspace 0.3.0

Run Codex CLI in Docker across saved single-folder or multi-folder workspaces.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

# codex-multi-workspace

[![CI](https://github.com/Honahec/codex-multi-workspace/actions/workflows/release.yml/badge.svg)](https://github.com/Honahec/codex-multi-workspace/actions/workflows/release.yml)
[![Crates.io](https://img.shields.io/crates/v/codex-multi-workspace.svg)](https://crates.io/crates/codex-multi-workspace)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

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 Ubuntu 22.04. It
includes Codex CLI, Node.js 22, Git, `curl`, and `bubblewrap`. Other language
runtimes can be installed per workspace with `runtime.apt` and `runtime.setup`,
or by selecting a custom Docker image.

## Install

```sh
cargo install codex-multi-workspace
```

## Create a Workspace

```sh
codex-ws workspace add my-workspace
```

This creates and opens:

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

Example:

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

# Optional runtime setup for the lightweight Ubuntu image.
# runtime:
#   apt:
#     - python3
#     - python3-pip
#   setup:
#     - python3 -m pip install --user maturin
```

List saved workspaces:

```sh
codex-ws workspace ls
```

## Configure cc-switch

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

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

Read it back:

```sh
codex-ws config get cc-switch-db
```

## Run

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

You can also pass a manifest path directly:

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

Workspace folders are mounted under `/workspace` using their original directory
names. A single-folder workspace starts Codex in that project directory. A
multi-folder workspace starts Codex in `/workspace`, with each project available
as `/workspace/<folder-name>`. Folder names must be unique within one workspace.

Codex runs with its internal command sandbox disabled inside the container. The
Docker container is the workspace boundary, and `sandbox.network: false` still
maps to Docker's `--network none`.

## Runtime Image

By default, `codex-ws` uses:

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

Override it when needed:

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

Workspace manifests can also request extra packages and setup commands before
Codex starts:

```yaml
runtime:
  apt:
    - python3
    - python3-pip
    - build-essential
  setup:
    - python3 -m pip install --user maturin
```

`runtime.apt` is installed with `apt-get install --no-install-recommends` inside
the container. `runtime.setup` commands run in a login shell immediately before
Codex, so PATH changes or sourced environment files can affect the Codex session.
For heavier stacks, use `runtime.image` in the manifest or `--image`.

**Welcome Stars and PRs.**