headquarter/openspec/specs/tool-instances/spec.md

Tool Instance Management Specification

Purpose

Launch, monitor, and manage development tool instances in Docker containers.

Requirements

Requirement: Tool Instance Creation

The system SHALL create and launch tool instances from repositories.

Scenario: Launch tool

• GIVEN an authenticated user with a project and repository
• WHEN they create a tool instance
• THEN:
  1. A unique subdomain is generated: {tool-name}-{tool-id}.hq.local
  2. The Docker Compose template is rendered with project values
  3. docker compose up -d is executed
  4. Container ID and status are stored

Requirement: Tool Lifecycle

The system SHALL manage tool lifecycle operations.

Scenario: Stop tool

• GIVEN a running tool instance
• WHEN the user stops it
• THEN docker compose stop is executed
• AND status is updated to "stopped"

Scenario: Start tool

• GIVEN a stopped tool instance
• WHEN the user starts it
• THEN docker compose start is executed
• AND status is updated to "running"

Scenario: Delete tool

• GIVEN a tool instance
• WHEN the user deletes it
• THEN the container and volumes are removed
• AND the database record is deleted

Requirement: Traefik Integration

The system SHALL auto-generate Traefik labels for routing.

Scenario: Route generation

• GIVEN a running tool instance
• THEN these labels are set:
  • traefik.enable=true
  • traefik.http.routers.{tool_id}.rule=Host(\{subdomain}.hq.local`)`
  • traefik.http.routers.{tool_id}.entrypoints=web
  • traefik.http.services.{tool_id}.loadbalancer.server.port={port}

Requirement: Status Monitoring

The system SHALL track tool status.

Scenario: Status check

• GIVEN a tool instance
• WHEN status is queried
• THEN the real-time container status is returned:
  • pending, building, running, stopped, error

Requirement: Log Access

The system SHALL provide access to container logs.

Scenario: View logs

• GIVEN a tool instance
• WHEN logs are requested
• THEN the last 100 lines are returned
• AND live streaming is available via WebSocket

Dependencies

• tool-types (tool definitions)
• git-repo (repository access)
• project-management (project context)
• Docker runtime
• Traefik reverse proxy

Quality Gates

• pytest must pass
• mypy . must pass
• ruff check . must pass
• npm run typecheck must pass
• npm run lint must pass