Release/v2.4.0 (#23)

kevinMEH · web-flow · commit 7567717ccc9c · 2026-04-03T16:21:05.000+08:00
- SEMI-BREAKING: Add new `~/.code-container/Dockerfile.User` for increased extensibility; add commands to `Dockerfile.User` to run custom commands instead of to a copy of `Dockerfile`.
- Reorganized documentation

---

* docs: Update documentation

* feat: Use Dockerfile.User
Replace ~/.code-container/Dockerfile with
~/.code-container/Dockerfile.User for improved extensibility

* docs: AGENTS.md: Remove old reference

* v2.4.0
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 node_modules
 dist
+internal
diff --git a/.ignore b/.ignore
@@ -0,0 +1 @@
+!internal
diff --git a/AGENTS.md b/AGENTS.md
@@ -10,7 +10,7 @@ If your user asks questions like:
 
 Then your user is a **consumer**.
 - The user is seeking your assistance in helping them setup or configure this project.
-- Next step: **Read `internal/ConsumerGuide.md`** and assist the user in installing or configurating `container`.
+- Next step: **Read `docs/ConsumerGuide.md`** and assist the user in installing or configurating `container`.
 
 If your user is a developer, proceed like normal.
 
@@ -30,84 +30,11 @@ If your user is a developer, proceed like normal.
 ## Key Features
 
 - **Security**: Destructive operations localized to containers
-- **Customization**: Add packages via `~/.code-container/Dockerfile`, mounts via `MOUNTS.txt`, flags via `DOCKER_FLAGS.txt` and `DOCKER_RUN_FLAGS.txt`
+- **Customization**: Add packages via `~/.code-container/Dockerfile.User`, mounts via `MOUNTS.txt`, flags via `DOCKER_FLAGS.txt` and `DOCKER_RUN_FLAGS.txt`
 - **Simultaneous Work**: Multiple agents can work on same project safely
 - **Persistence**: Container state and harness configs persist
 
 ## Requirements
 
 - Docker (Desktop or Engine)
 - POSIX system (Linux, macOS, WSL)
-
----
-
-# Project Index
-
-**Important Rule: Always update this index after creating new code files or making significant changes to existing files.**
-
-## Directory Structure
-
-```
-/root/code-container/
-├── src/                    # TypeScript source code (main codebase)
-├── scripts/                # Utility scripts (install, migrate, cleanup)
-├── internal/               # Internal documentation
-├── dist/                   # Compiled JavaScript output (generated)
-├── .github/workflows/      # CI/CD workflows
-├── Dockerfile              # Container image definition
-├── package.json            # NPM package manifest
-└── tsconfig.json           # TypeScript configuration
-```
-
-## Source Files Index (`src/`)
-
-### Entry Point
-
-- `src/main.ts` — CLI entry point. Parses arguments, displays TOS, routes to commands. Supports: `run`, `build`, `init`, `stop`, `remove`, `list`, `clean`.
-
-### Core Modules
-
-- `src/commands.ts` — Business logic for all CLI commands. Image building, container lifecycle, listing, cleaning. Exports: `buildImage`, `init`, `runContainer`, `stopContainerForProject`, `removeContainerForProject`, `listContainers`, `cleanContainers`
-- `src/docker.ts` — Low-level Docker CLI wrappers. Image/container operations, interactive sessions, naming via SHA1 hash. Exports: `checkDocker`, `imageExists`, `buildImageRaw`, `containerExists`, `containerRunning`, `createNewContainer`, `execInteractive`, `stopContainer`, `startContainer`, `removeContainer`, `generateContainerName`
-- `src/config.ts` — Configuration paths and settings persistence. Manages `~/.code-container/` directory. Exports: `APPDATA_DIR`, `CONFIGS_DIR`, `DOCKERFILE_PATH`, `SETTINGS_PATH`, `MOUNTS_PATH`, `FLAGS_PATH`, `RUN_FLAGS_PATH`, `loadSettings`, `saveSettings`, `copyConfigs`, `ensureConfigDir`
-- `src/mounts.ts` — Volume mount management. Core mounts (configs, gitconfig) and optional SSH mounting. Exports: `ensureMountsFile`, `loadMounts`, `getCoreMounts`
-- `src/flags.ts` — Custom Docker flags loaders from `DOCKER_FLAGS.txt` and `DOCKER_RUN_FLAGS.txt`. Uses shell-quote for safe parsing. `DOCKER_FLAGS.txt` is loaded for both `docker run` and `docker exec`. `DOCKER_RUN_FLAGS.txt` is loaded only for `docker run`. Exports: `loadFlags`, `loadRunFlags`
-- `src/utils.ts` — Colored console output and user prompts. Exports: `printInfo`, `printSuccess`, `printWarning`, `printError`, `promptYesNo`, `resolveProjectPath`
-
-## Scripts Index (`scripts/`)
-
-- `scripts/postinstall.js` — NPM post-install hook. Creates `~/.code-container/` structure, copies default Dockerfile, and creates `DOCKER_FLAGS.txt` and `DOCKER_RUN_FLAGS.txt`.
-- `scripts/migrate.sh` — Migrates config files from old shell script location to new `~/.code-container/configs/`.
-- `scripts/cleanup.sh` — Removes old config files from project root after migration.
-
-## Storage Structure
-
-All user data stored in `~/.code-container/`:
-
-```
-~/.code-container/
-├── configs/          # Harness configs (mounted to containers)
-│   ├── .claude/
-│   ├── .claude.json
-│   ├── .codex/
-│   ├── .copilot/
-│   ├── .gemini/
-│   ├── .local/
-│   └── .opencode/
-├── Dockerfile        # Custom Dockerfile
-├── MOUNTS.txt              # Additional mount points
-├── DOCKER_FLAGS.txt        # Docker flags for both run and exec
-├── DOCKER_RUN_FLAGS.txt    # Docker flags for run only
-└── settings.json           # Internal settings
-```
-
-## CLI Commands
-
-- `container [path]` — Run container for project (`commands.ts:runContainer`)
-- `container run [path] [-- DOCKER_FLAGS]` — Run container with optional Docker flags
-- `container build` — Build Docker image (`commands.ts:buildImage`)
-- `container init` — Initialize config files (`commands.ts:init`)
-- `container stop` — Stop container (`commands.ts:stopContainerForProject`)
-- `container remove` — Remove container (`commands.ts:removeContainerForProject`)
-- `container list` — List all containers (`commands.ts:listContainers`)
-- `container clean` — Remove stopped containers (`commands.ts:cleanContainers`)
diff --git a/Dockerfile.User b/Dockerfile.User
@@ -0,0 +1,3 @@
+# User customizations for code-container
+# Add your RUN, ENV, COPY, etc. directives below.
+FROM code-container-base:latest
diff --git a/README.md b/README.md
@@ -93,7 +93,7 @@ container init             # Copy/recopy config files
 
 Destructive actions are localized inside containers.
 - You can let your harness run with full permissions
-- To configure your harness to run without permissions, see [`Permissions.md`](Permissions.md).
+- To configure your harness to run without permissions, see [`Permissions.md`](docs/Permissions.md).
 
 ### Customization
 
@@ -106,12 +106,16 @@ Destructive actions are localized inside containers.
 
 Easily add your own tooling & mount points.
 
-**Adding tools/packages**: Edit `~/.code-container/Dockerfile` and rebuild:
+**Adding tools/packages**: Edit `~/.code-container/Dockerfile.User` and rebuild:
 
 ```dockerfile
+FROM code-container-base:latest
+
 RUN apt-get update && apt-get install -y postgresql-client redis-tools
 ```
 
+> **Deprecation Notice**: `~/.code-container/Dockerfile` is deprecated and no longer used. If you previously customized this file, migrate your custom `RUN` commands to `~/.code-container/Dockerfile.User`.
+
 **Adding mount points**: Edit `~/.code-container/MOUNTS.txt` and reinitialize containers:
 
 ```
diff --git a/docs/ConsumerGuide.md b/docs/ConsumerGuide.md
@@ -22,7 +22,7 @@ Setup: Do for the user, one step at a time.
    ```bash
    container init
    ```
-3. Setup is done. Now, read `~/.code-container/Dockerfile`, which is the default packaged Dockerfile. Provide a brief list of included packages to the user. Then, ask user if they would like to add more packages into container environment. If yes, see `Add Packages/Dependencies` section below.
+3. Setup is done. Now, read the `Dockerfile` and the user's `~/.code-container/Dockerfile.User` if exists. Provide a brief list of included packages to the user. Then, ask user if they would like to add more packages into container environment. If yes, see `Add Packages/Dependencies` section below.
 4. Build the Docker image for the user. Before you build, tell the user that building the image may take up to 5 minutes.
    ```bash
    container build
@@ -60,19 +60,23 @@ All container data is stored in `~/.code-container/`:
 │   ├── .gemini/
 │   ├── .local/
 │   └── .opencode/
-├── Dockerfile        # Custom Dockerfile
+├── Dockerfile.User    # User customizations layered on base image
 ├── MOUNTS.txt        # Additional mount points
 ├── DOCKER_FLAGS.txt  # Additional docker run flags
 └── settings.json     # Internal settings
 ```
 
 ## Customization
 
-### Add Packages/Dependencies (Dockerfile)
+### Add Packages/Dependencies (Dockerfile.User)
 
-Add new tools by extending the RUN commands in `~/.code-container/Dockerfile`:
+> **Deprecation Notice**: `~/.code-container/Dockerfile` is deprecated and no longer used. If the user previously customized this file, offer to migrate their custom `RUN` commands to `~/.code-container/Dockerfile.User`.
+
+Add new tools by editing `~/.code-container/Dockerfile.User`:
 
 ```dockerfile
+FROM code-container-base:latest
+
 # System packages (Ubuntu/Debian)
 RUN apt-get update && apt-get install -y \
     postgresql-client \
@@ -126,6 +130,6 @@ Each line is parsed like a shell command. Empty lines and lines starting with `#
 
 ## Harness Permissions
 
-If the user asks you to configure harnesses to run without permission prompts inside `container`, read and follow instructions in [Permissions.md](/Permissions.md).
+If the user asks you to configure harnesses to run without permission prompts inside `container`, read and follow instructions in [Permissions.md](/docs/Permissions.md).
 
 Note: Modify the configuration files inside `~/.code-container/configs` only.
diff --git a/docs/Permissions.md b/docs/Permissions.md
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "code-container",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Manage isolated Docker containers for running coding tools on different projects",
   "main": "dist/main.js",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "dist",
     "scripts",
-    "Dockerfile"
+    "Dockerfile",
+    "Dockerfile.User"
   ],
   "scripts": {
     "build": "tsc && chmod u+x dist/main.js",
diff --git a/scripts/postinstall.js b/scripts/postinstall.js
@@ -6,10 +6,10 @@ const os = require("os");
 
 const APPDATA_DIR = path.join(os.homedir(), ".code-container");
 const CONFIGS_DIR = path.join(APPDATA_DIR, "configs");
-const DOCKERFILE_PATH = path.join(APPDATA_DIR, "Dockerfile");
+const USER_DOCKERFILE_PATH = path.join(APPDATA_DIR, "Dockerfile.User");
+const PACKAGED_USER_DOCKERFILE = path.join(__dirname, "..", "Dockerfile.User");
 const FLAGS_PATH = path.join(APPDATA_DIR, "DOCKER_FLAGS.txt");
 const RUN_FLAGS_PATH = path.join(APPDATA_DIR, "DOCKER_RUN_FLAGS.txt");
-const PACKAGED_DOCKERFILE = path.join(__dirname, "..", "Dockerfile");
 
 if (!fs.existsSync(APPDATA_DIR)) {
   fs.mkdirSync(APPDATA_DIR, { recursive: true, mode: 0o700 });
@@ -19,8 +19,8 @@ if (!fs.existsSync(CONFIGS_DIR)) {
   fs.mkdirSync(CONFIGS_DIR, { recursive: true, mode: 0o700 });
 }
 
-if (!fs.existsSync(DOCKERFILE_PATH)) {
-  fs.copyFileSync(PACKAGED_DOCKERFILE, DOCKERFILE_PATH);
+if (!fs.existsSync(USER_DOCKERFILE_PATH)) {
+  fs.copyFileSync(PACKAGED_USER_DOCKERFILE, USER_DOCKERFILE_PATH);
 }
 
 if (!fs.existsSync(FLAGS_PATH)) {
diff --git a/src/config.ts b/src/config.ts
@@ -5,7 +5,7 @@ import { z } from "zod";
 
 export const APPDATA_DIR = path.join(os.homedir(), ".code-container");
 export const CONFIGS_DIR = path.join(APPDATA_DIR, "configs");
-export const DOCKERFILE_PATH = path.join(APPDATA_DIR, "Dockerfile");
+export const USER_DOCKERFILE_PATH = path.join(APPDATA_DIR, "Dockerfile.User");
 export const SETTINGS_PATH = path.join(APPDATA_DIR, "settings.json");
 export const MOUNTS_PATH = path.join(APPDATA_DIR, "MOUNTS.txt");
 export const FLAGS_PATH = path.join(APPDATA_DIR, "DOCKER_FLAGS.txt");
diff --git a/src/docker.ts b/src/docker.ts
@@ -3,13 +3,15 @@ import * as path from "path";
 import * as fs from "fs";
 import * as crypto from "crypto";
 import { printInfo, printError } from "./utils";
-import { APPDATA_DIR, DOCKERFILE_PATH } from "./config";
+import { APPDATA_DIR, USER_DOCKERFILE_PATH } from "./config";
 import { loadMounts } from "./mounts";
 import { loadFlags, loadRunFlags } from "./flags";
 
 export const IMAGE_NAME = "code-container";
 export const IMAGE_TAG = "latest";
+export const BASE_IMAGE = "code-container-base";
 const PACKAGED_DOCKERFILE = path.resolve(__dirname, "..", "Dockerfile");
+const PACKAGED_USER_DOCKERFILE = path.resolve(__dirname, "..", "Dockerfile.User");
 const CONTAINER_PREFIX = "container";
 
 export function checkDocker(): void {
@@ -51,28 +53,36 @@ export function imageExists(): boolean {
 }
 
 export function ensureDockerfile(): void {
-  if (!fs.existsSync(DOCKERFILE_PATH)) {
-    if (fs.existsSync(PACKAGED_DOCKERFILE)) {
+  if (!fs.existsSync(USER_DOCKERFILE_PATH)) {
+    if (fs.existsSync(PACKAGED_USER_DOCKERFILE)) {
       printInfo(
-        `Dockerfile not found at ${DOCKERFILE_PATH}, copying from package...`
+        `Dockerfile.User not found at ${USER_DOCKERFILE_PATH}, copying from package...`
       );
-      fs.copyFileSync(PACKAGED_DOCKERFILE, DOCKERFILE_PATH);
+      fs.copyFileSync(PACKAGED_USER_DOCKERFILE, USER_DOCKERFILE_PATH);
     } else {
       throw new Error(
-        `Dockerfile not found at ${DOCKERFILE_PATH} and no packaged Dockerfile available`
+        `Dockerfile.User not found at ${USER_DOCKERFILE_PATH} and no packaged Dockerfile.User available`
       );
     }
   }
 }
 
 export function buildImageRaw(): boolean {
+  const baseResult = spawnSync(
+    "docker",
+    ["build", "-t", `${BASE_IMAGE}:${IMAGE_TAG}`, "-f", PACKAGED_DOCKERFILE, APPDATA_DIR],
+    { stdio: "inherit" }
+  );
+  if (baseResult.status !== 0) return false;
+
   ensureDockerfile();
-  const result = spawnSync(
+
+  const userResult = spawnSync(
     "docker",
-    ["build", "-t", `${IMAGE_NAME}:${IMAGE_TAG}`, APPDATA_DIR],
+    ["build", "-f", USER_DOCKERFILE_PATH, "-t", `${IMAGE_NAME}:${IMAGE_TAG}`, APPDATA_DIR],
     { stdio: "inherit" }
   );
-  return result.status === 0;
+  return userResult.status === 0;
 }
 
 export function containerExists(containerName: string): boolean {

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`node_modules`
`2`	`2`	`dist`
	`3`	`+internal`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# User customizations for code-container`
	`2`	`+# Add your RUN, ENV, COPY, etc. directives below.`
	`3`	`+FROM code-container-base:latest`