Files

T

Alex Blank 3e99e7f197 feat: legacy fallback tests and docs (PR 3)

- Add test_tool_instances_legacy.py with 8 unit tests:
  - dockerfile definition type builds from template
  - dockerfile build failure raises HTTP 500
  - compose definition type renders template
  - manifest compiler is NOT called for legacy types
  - start_instance legacy/compose/dockerfile types all skip manifest flow
  - start_instance manifest type correctly invokes compiler
- Mark T3.2 and T3.3 tasks complete in OpenSpec
- Add openspec/docs/tool-workshop-guide.md with user guide covering
  definition types, manifest creation workflow, base definitions,
  migration path, and permissions

2026-05-28 14:54:32 +02:00

3.1 KiB

Raw Blame History

Tool Workshop User Guide

Overview

The Tool Workshop lets you define and manage tool types — the blueprints for containers that run inside Headquarter. Each tool type specifies how to build and start a container (Docker image, Compose file, or a declarative manifest).

Definition Types

1. Compose (Legacy)

Write a raw Docker Compose template. Variable substitution is supported:

${REPO_PATH} — path to the mounted repository
${TOOL_PORT} — dynamically assigned free port
${INSTANCE_NAME} — generated instance name
${USER_ID}, ${PROJECT_ID} — IDs for reference

Best for: simple web services, databases, or anything that already has a Docker image.

2. Dockerfile (Legacy)

Write a raw Dockerfile. Headquarter builds the image and generates a minimal Compose file automatically.

Best for: custom environments where you need full control over the image build.

3. Manifest (Declarative) — Recommended

Define your tool with structured JSON instead of raw Docker files:

Base image — pick a base definition (e.g. ubuntu-24.04-dev)
Packages — declare apt, npm global, pip, and Node.js version
Scripts — build scripts (run at image build time) and startup scripts (run when container starts)
Mounts — workspace, SSH keys, instance state, git-mounted dotfiles
Runtime — command, working directory, stdin/tty settings
Live preview — see generated Dockerfile and Compose as you edit

Best for: reproducible, versioned, self-documenting tool definitions.

Creating a Manifest-Based Tool

Go to Settings → Tool Workshop
Click New Tool Type
Select Manifest (Declarative) as the definition type
Choose a Base Image (e.g. ubuntu-24.04-dev v1)
Add packages:
- Apt: neovim, tmux, git
- NPM global: @earendil-works/pi-coding-agent
- Node.js version: 20
Add build scripts (e.g. configure git defaults)
Add startup scripts (e.g. fix workspace permissions)
Configure mounts:
- Workspace → /workspace (writable)
- SSH keys → /home/user/.ssh (readonly, mode 0700)
Set runtime: command /bin/bash, working dir /workspace
Click Preview to verify generated Dockerfile and Compose
Save

Base Definitions

Base definitions are versioned manifest templates that other tools extend. They are marked with the Base badge in the list.

The default base ubuntu-24.04-dev provides:

Ubuntu 24.04 base image
Common build tools (curl, wget, git, build-essential)
A non-root user account (uid 1000)

Migration from Legacy

Existing tool types using Compose or Dockerfile continue to work unchanged. You can migrate a tool type to Manifest by:

Editing the tool type
Switching definition type to Manifest
Re-creating the configuration in the manifest editor
Saving (the old template is cleared automatically)

Permissions

For manifest-based tools, mount permissions are fixed automatically after the container starts. The system runs chown and chmod via docker exec as root, then drops back to the configured runtime user.

3.1 KiB Raw Blame History