headquarter/openspec/changes/tool-config-management/design.md

Context

Tool instances currently start with hardcoded compose templates. There's no way for users to provide API keys (OpenAI, Anthropic), custom settings, or files that tools need. We need a flexible config system that supports both environment variables and file-based configs.

Goals / Non-Goals

Goals:

• Store tool configs per user (global) and per project
• Support env vars and file-based configs
• Mount configs into containers at startup
• Add tool categories (editor, notebook, ai-assistant)
• Add interface types (web, terminal) to control UI
• Add OpenCode as built-in terminal tool

Non-Goals:

• Secret encryption at rest (for now)
• Config validation beyond basic type checking
• Per-instance configs (only global and project-scoped)

Decisions

Config scope: user-global and user+project

Decision: Two scopes - global (user-level) and project-specific (user+project level)

Rationale: Some configs (like OpenAI API key) are user-global. Others (like project-specific paths) are per-project.

Config types: env and file

Decision: Support two config types: env (injected as environment variables) and file (written to files and mounted)

Rationale: Most tools need env vars. Some (like OpenCode) need config files.

Tool categories as enum

Decision: Predefined categories: editor, notebook, ai-assistant, other

Rationale: Simple, predictable, drives UI behavior.

Interfaces as array

Decision: ToolType.interfaces is a JSON array of strings: ["web"], ["terminal"], ["web", "terminal"]

Rationale: Flexible, allows combination interfaces.

Risks / Trade-offs

[Risk] Config files in container filesystem are readable by any process in container → Mitigation: Document this. Future: use Docker secrets for sensitive values.

[Risk] Storing API keys in plain text in database → Mitigation: Acceptable for MVP. Future: encrypt sensitive configs.

Migration Plan

1. Create migrations for tool_types (category, interfaces) and tool_configs tables
2. Update seed data for built-in types
3. Deploy backend changes
4. Update frontend to show categories and config UI
5. Test with OpenCode instance

Open Questions

• Should we encrypt sensitive configs now or later?
• Do we need config templates/tooling per tool type?