headquarter/openspec/designs/tool-container-home-directory.md

# Design / ADR: Tool Container Home Directory

## Status

Proposed

## Context

Tool containers currently mix home-directory conventions:

- Legacy `dockerfile` and `compose` tool types mount the repository at `/workspace` and run as `root`.
- Manifest-based tool types may run as a non-root user (`user`) and already support `~` / `$HOME` expansion to `/home/{user.name}` via the `home-path-expansion` work.
- `tool-images/base.dockerfile` already creates a `user` with `WORKDIR /home/user`, but the platform does not guarantee this for all tool types.

Users expect a predictable, writable home directory inside every tool container and want the repository/workspace to live under it, preserving the repository's root directory name so paths are meaningful (e.g., `/home/user/my-app`, not `/home/user/workspace` or a generic `/workspace`).

## Goals

1. Provide a **configurable workspace/home directory** that **defaults to `/home/user`** for all tool containers.
2. Mount the repository/workspace under that directory using the **actual directory name** (`{repo_name}` or `{workspace_name}`).
3. Make the setting part of the **ToolType / manifest definition** so tool authors control it.
4. Keep **`manifest.user.name`** as the runtime user; the new field controls the directory path.
5. Preserve **`/workspace` as a compatibility symlink** to avoid breaking existing scripts, bookmarks, and settings.
6. Ensure **config-profile and git mounts** staged by the API remain writable by the non-root container user.

## Non-Goals

- Changing the container runtime user model (still driven by `manifest.user`).
- Moving non-tool services (API, web, Postgres, Redis) under `/home/user`.
- Forcing every existing manifest to migrate; explicit repo mount targets remain respected.
- Adding a frontend UI for the new field in this iteration (backend field + manifest schema change only).

## Decision

### Configuration surface

Add a `home_directory` field to the ToolType model and the manifest schema. It defaults to `/home/user` and can be overridden per tool type.

- **ToolType level**: `ToolType.home_directory: str = "/home/user"` (non-nullable, default).
- **Manifest level**: `manifest.home_directory: str` (optional; if absent, fall back to `ToolType.home_directory`).

The runtime home directory for a container is resolved in this precedence order:

1. Manifest `home_directory` if present.
2. ToolType `home_directory` (database column, default `/home/user`).
3. Legacy fallback: `/root` for compose/dockerfile tools without the new field.

### What `home_directory` controls

1. **Repository/workspace mount target** when no explicit repo mount is defined:
   - Repositories: `{home_directory}/{repo_name}`
   - Workspaces: `{home_directory}/{workspace_name}` (fall back to `{repo_name}`)
2. **Dockerfile `HOME` environment variable** for manifest tools: `ENV HOME={home_directory}`.
3. **Dockerfile `WORKDIR`** for manifest tools (when no explicit `runtime.working_dir` overrides it).
4. **Base for `~` / `$HOME` expansion** in config-profile mounts and git-mount mappings.

### Precedence: explicit manifest mount wins

If a manifest already contains a mount with `source_type: repo` and an explicit `target`, that target is used unchanged. `home_directory` is only used to synthesize the default repo/workspace mount when none is explicitly specified.

### Migration for legacy tools

Use an **Alembic data migration**:

1. Add `home_directory` column to `tool_types`.
2. Set existing rows to `/home/user`.
3. Rewrite stored `compose_template` and `dockerfile_template` strings to replace `/workspace` with `{home_directory}/{{WORKSPACE_NAME}}` (or equivalent template variable) where the mount target is the workspace.

The migration is reversible via downgrade: restore the original `/workspace` strings and drop the column.

### `/workspace` compatibility

Keep `/workspace` as a symlink inside the container pointing to the resolved repo/workspace target (e.g., `/home/user/my-app`). This protects:

- Existing user startup commands and scripts.
- Bookmarks and IDE settings that reference `/workspace`.
- Legacy templates that were migrated.

The symlink is created by the generated Dockerfile (or startup entrypoint) because the actual repo is mounted at runtime.

### Permission model

Use an **entrypoint permission fixer** at container startup:

- Run as `root` (or via `sudo`) before switching to the runtime user.
- Chown mounted paths under `{home_directory}` to the container user.
- Avoid `chown -R` on large repo subtrees; chown the top-level directories and rely on the runtime user owning newly created files.
- This handles config-profile and git mounts that arrive at runtime as bind mounts from the host, which may otherwise be owned by `root` because the API stages them.

## Consequences

### Positive

- Predictable, user-writable home directory across all tool containers.
- Repository mount paths are meaningful (`/home/user/my-app`).
- Backward-compatible symlink keeps existing user data and scripts working.
- Tool authors can opt into other home directories without changing the runtime user.

### Negative / Risks

- Requires an Alembic data migration that rewrites stored templates; downgrade must be carefully tested.
- Entrypoint permission fixer adds startup complexity and requires `root`/`sudo` inside the container.
- Creating `/workspace` symlink at build time vs. runtime needs care because the target may not exist until the repo is mounted.
- Legacy `tool-images/base.dockerfile` runs as `USER user`; it will need an entrypoint that can elevate permissions or the base image must be adjusted.

## Related Documents

- `openspec/designs/home-path-expansion.md`
- `openspec/specs/home-path-expansion.md`
- `openspec/tasks/home-path-expansion.md`
- `docs/superpowers/plans/tool-container-home-directory.md`
- `docs/superpowers/specs/tool-container-home-directory-test-plan.md`