Files
headquarter/openspec/changes/tool-config-mount-cleanup/proposal.md
T
Developer 8bde9a213c feat: remove config/state mounts from built-in tool configs
- Remove pi_state and pi_config mounts from the pi-agent manifest.
- Add Alembic data migration to strip those mounts from existing DB rows.
- Remove opencode_home:/tmp volume and HOME=/tmp override from the opencode
  built-in compose template; config/state now belongs in config profiles.
- Workspace and SSH key mounts remain unchanged.

Quality gates: python3 -m py_compile, pytest (311 passed, 34 skipped),
npm run typecheck, npm run lint
2026-06-13 11:35:55 +00:00

1.5 KiB

Tool config mount cleanup

Problem

The built-in tool definitions currently declare configuration and state mounts that belong in user-controlled config profiles:

  • The pi-agent manifest mounts pi_state (/tmp/.pi/agents) and pi_config (/home/user/.pi) via a git_mount reference.
  • The opencode built-in compose template mounts a named volume opencode_home:/tmp and sets HOME=/tmp.

These require manual configuration or implicit state persistence, which conflicts with the design that tool configs should only set up the actual tool, while config profiles handle user-specific configuration and state.

Decision

Remove all configuration/state mounts from built-in tool definitions. Tool configs will declare only:

  • Runtime environment (packages, user, command, ports).
  • The workspace/repository mount.
  • SSH key mounts supplied by the platform.

User-specific configuration and state will be handled exclusively by config profiles.

Scope

  • Remove pi_state and pi_config mounts from the pi-agent manifest.
  • Update the original migration that inserts the pi-agent manifest.
  • Add a data migration to remove those mounts from existing tool_definition_manifests rows.
  • Remove the opencode_home:/tmp volume and HOME=/tmp override from the opencode built-in compose template.

Non-goals

  • No changes to config profile behavior.
  • No changes to workspace or SSH key mounts.
  • No changes to tool image Dockerfiles beyond what is required by mount removal.