headquarter/openspec/changes/archive/2026-05-19-tool-instances/specs/spec.md

Tool Instances Specification

Requirements

Functional Requirements

1. ToolInstance Model: Store instance metadata with status tracking
2. Session API: CRUD operations + lifecycle (start/stop/restart/delete)
3. Docker Integration: Render compose templates and execute commands
4. Status Monitoring: Real-time container status polling
5. Log Access: View container logs (last 100 lines)
6. Session Navigation: Active sessions appear in app shell
7. URL Generation: Unique access URLs for each running instance

Non-Functional Requirements

1. Security: Isolated containers, no privileged mode
2. Resource Limits: CPU and memory constraints
3. Error Handling: Graceful failure with cleanup
4. Performance: Start time < 30 seconds

API Specification

Create Instance

POST /projects/{project_id}/repositories/{repo_id}/instances
Body: {
  tool_type_id: string,
  display_name: string (optional)
}
Response: {
  id: string,
  name: string,
  display_name: string,
  tool_type_id: string,
  status: "pending",
  created_at: string
}

List Instances

GET /projects/{project_id}/repositories/{repo_id}/instances
Response: {
  instances: [...]
}

Get Instance

GET /projects/{project_id}/repositories/{repo_id}/instances/{instance_id}
Response: {
  id: string,
  name: string,
  display_name: string,
  status: string,
  container_id: string | null,
  url: string | null,
  port: number | null,
  last_started_at: string | null,
  last_stopped_at: string | null,
  created_at: string
}

Lifecycle Operations

POST /projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/start
POST /projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/stop
POST /projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/restart
Response: { status: string }

Delete Instance

DELETE /projects/{project_id}/repositories/{repo_id}/instances/{instance_id}
Response: 204 No Content

Get User Sessions

GET /users/me/sessions
Response: {
  sessions: [
    {
      id: string,
      display_name: string,
      tool_type_name: string,
      tool_icon: string,
      repository_name: string,
      project_name: string,
      status: string,
      url: string | null
    }
  ]
}

Docker Compose Template Variables

• {{REPO_PATH}}: Absolute path to git repository on host
• {{INSTANCE_NAME}}: Unique instance identifier
• {{INSTANCE_ID}}: UUID of the instance
• {{TOOL_PORT}}: Assigned port for the tool
• {{USER_ID}}: Owner user ID
• {{PROJECT_ID}}: Project ID

Status Values

• pending: Instance created, waiting to start
• building: Docker compose up in progress
• running: Container is running
• stopped: Container stopped
• error: Container failed to start or crashed

Database Schema

CREATE TABLE tool_instances (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    display_name VARCHAR(255) NOT NULL,
    tool_type_id UUID NOT NULL REFERENCES tool_types(id),
    repository_id UUID NOT NULL REFERENCES git_repositories(id),
    project_id UUID NOT NULL REFERENCES projects(id),
    owner_id UUID NOT NULL REFERENCES users(id),
    status VARCHAR(50) NOT NULL DEFAULT 'pending',
    container_id VARCHAR(255),
    compose_path VARCHAR(1024),
    url VARCHAR(1024),
    port INTEGER,
    last_started_at TIMESTAMP WITH TIME ZONE,
    last_stopped_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_tool_instances_owner ON tool_instances(owner_id);
CREATE INDEX idx_tool_instances_repo ON tool_instances(repository_id);
CREATE INDEX idx_tool_instances_status ON tool_instances(status);

Testing Requirements

1. Unit Tests: Docker command generation, template rendering
2. Integration Tests: API endpoints, database operations
3. Manual Testing: Container lifecycle, navigation updates