headquarter/openspec/changes/archive/2026-05-23-remove-built-in-tools/design.md

Context

Currently, the system seeds built-in tool types (code-server, jupyter-notebook, opencode) on every startup via seed_builtin_tool_types() in main.py. These are marked with is_builtin=True in the database and have special protections preventing their deletion or modification. This creates a two-tier system.

Goals / Non-Goals

Goals:

• Remove is_builtin field from ToolType model and API
• Remove startup seeding logic
• Make all tool types editable and deletable
• Preserve existing tool type data by converting built-ins to regular types

Non-Goals:

• Changing the actual tool type definitions (compose templates, ports, etc.)
• Adding new tool types
• Changing the tool type creation API schema

Decisions

1. Data Migration Over Runtime Seeding

Decision: Move built-in tool definitions from Python code to a database migration.

Rationale:

• Makes built-ins regular database records
• Eliminates special-case code paths
• Allows users to modify or delete them freely
• Simplifies the codebase

2. Drop is_builtin Column

Decision: Remove the is_builtin column entirely rather than setting all to False.

Rationale:

• Clean schema with no dead columns
• No confusion about what the flag means
• Simpler model

Risks / Trade-offs

[Risk] Users accidentally delete preconfigured tools → Mitigation: These are just regular tool types now; users can recreate them manually if needed. The system no longer auto-recreates them.

[Risk] Existing code depends on is_builtin flag → Mitigation: Comprehensive search and removal of all references.

Migration Plan

1. Create Alembic migration to:
   • Add definition_type and dockerfile_template columns if not present (some built-ins use these)
   • Insert built-in tool types as regular records (if they don't exist)
   • Drop is_builtin column
2. Remove seed_builtin_tool_types() from main.py
3. Update ToolType model to remove is_builtin
4. Update API to remove built-in checks
5. Update frontend to remove built-in-specific UI

Open Questions

• Should we keep a seed script for fresh installations? (Yes, as a one-time migration)