headquarter/docs/features/tool-types.md

Tool Types

Overview

Tool types define development tools that can be spawned for projects. Headquarter includes built-in types and supports creating custom tool types with Docker Compose templates.

How to Use

Built-in Tool Types

Headquarter includes these built-in tool types:

VS Code Server

• Image: lscr.io/linuxserver/code-server:latest
• Purpose: Full VS Code in the browser
• Features: Extensions, terminal, debugging
• Access: Port 8443

Jupyter Notebook

• Image: jupyter/scipy-notebook:latest
• Purpose: Interactive Python development
• Features: Notebooks, data visualization
• Access: Port 8888

Managing Tool Types

Viewing Tool Types

1. Navigate to Settings → Tool Types
2. See a list of all tool types
3. Built-in types are marked with a badge

Creating Custom Tool Types

1. Click "New Tool Type"
2. Fill in the form:
   • Name: Unique identifier (e.g., my-custom-tool)
   • Display Name: Human-readable name
   • Description: What this tool does
   • Compose Template: Docker Compose YAML
3. Click "Create"

Compose Template Format

The compose template uses Docker Compose syntax with template variables:

version: "3.8"
services:
  my-tool:
    image: my-image:latest
    container_name: {{TOOL_NAME}}
    environment:
      - VARIABLE=value
    volumes:
      - {{REPO_PATH}}:/workspace
    ports:
      - "8080:8080"

Required Variables:

• {{TOOL_NAME}} - Unique name for the container
• {{REPO_PATH}} - Path to the repository

Git Requirement for Clone Mode

When users create instances in clone mode (fresh repository copy instead of bind mount), the container image must have git installed. This enables git operations (push, pull, branch) inside the container.

Built-in types with git:

• VS Code Server: Includes git
• Jupyter Notebook: Includes git
• OpenCode: Installs git during startup

Custom tool types: Ensure your base image includes git (e.g., apt-get install -y git in Dockerfile).

Validating Templates

The system validates templates:

• Must be valid YAML
• Must contain a services section
• Must use all required variables
• Invalid templates will be rejected

Editing Tool Types

1. Find the tool type in the list
2. Click "Edit"
3. Update fields
4. Click "Save"

Note: Built-in tool types cannot be modified or deleted.

Deleting Tool Types

1. Find the tool type in the list
2. Click "Delete"
3. Confirm deletion

Note: Built-in tool types cannot be deleted.

API Reference

Endpoints

• GET /tool-types - List tool types
• POST /tool-types - Create tool type
• GET /tool-types/{id} - Get tool type details
• PUT /tool-types/{id} - Update tool type
• DELETE /tool-types/{id} - Delete tool type

See Tool Types API for detailed endpoint documentation.

Related Features

• Tool Instances - Spawn and manage tool instances