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

Tool Instances - Design

Architecture

Tool Instance System
├── Backend
│   ├── ToolInstance Model
│   ├── Session API (CRUD + lifecycle)
│   ├── Docker Service (compose execution)
│   └── Status Polling
├── Frontend
│   ├── SessionStore (active sessions)
│   ├── AppShell Integration (nav entries)
│   ├── Instance Manager (repo page)
│   └── Session Launcher (create dialog)
└── Docker
    ├── Compose Template Rendering
    ├── Container Execution
    └── Volume Management

Data Model

ToolInstance

class ToolInstance(Base):
    id: UUID
    name: str  # Generated: "vscode-myrepo-abc123"
    display_name: str  # User-friendly name
    tool_type_id: UUID -> ToolType
    repository_id: UUID -> GitRepository
    project_id: UUID -> Project
    owner_id: UUID -> User
    status: str  # pending, building, running, stopped, error
    container_id: str | None
    compose_path: str | None  # Path to rendered compose file
    url: str | None  # Access URL
    port: int | None
    last_started_at: datetime | None
    last_stopped_at: datetime | None
    created_at: datetime
    updated_at: datetime

API Design

Endpoints

POST   /projects/{id}/repositories/{id}/instances
GET    /projects/{id}/repositories/{id}/instances
GET    /projects/{id}/repositories/{id}/instances/{id}
PUT    /projects/{id}/repositories/{id}/instances/{id}
DELETE /projects/{id}/repositories/{id}/instances/{id}
POST   /projects/{id}/repositories/{id}/instances/{id}/start
POST   /projects/{id}/repositories/{id}/instances/{id}/stop
POST   /projects/{id}/repositories/{id}/instances/{id}/restart
GET    /projects/{id}/repositories/{id}/instances/{id}/status
GET    /projects/{id}/repositories/{id}/instances/{id}/logs
GET    /users/me/sessions  # Active sessions for nav

Docker Integration

Compose Template Rendering

# Template variables:
# {{REPO_PATH}} - Absolute path to repo
# {{INSTANCE_NAME}} - Unique instance name
# {{TOOL_PORT}} - Exposed port

services:
  {{INSTANCE_NAME}}:
    image: codercom/code-server:latest
    volumes:
      - {{REPO_PATH}}:/workspace
    ports:
      - "{{TOOL_PORT}}:8080"
    environment:
      - PASSWORD={{INSTANCE_NAME}}

Execution Flow

1. Create instance directory: data/instances/{instance_id}/
2. Render compose file to docker-compose.yml
3. Run docker compose -f {path} up -d
4. Capture container ID from output
5. Poll status until running or error

Frontend Integration

Session Store

interface Session {
  id: string;
  name: string;
  displayName: string;
  toolType: string;
  toolIcon: string;
  repositoryId: string;
  projectId: string;
  status: "pending" | "running" | "stopped" | "error";
  url: string | null;
}

const useSessions = () => {
  const sessions = useAtom(sessionsAtom);
  const addSession = (session: Session) => { ... };
  const removeSession = (id: string) => { ... };
  const updateStatus = (id: string, status: string) => { ... };
  return { sessions, addSession, removeSession, updateStatus };
};

AppShell Navigation

• Add "Sessions" section in nav
• Show active sessions with tool icons
• Session status indicator (green dot for running)
• Click opens tool in new tab
• Dropdown for managing sessions

Repository Page

• "Launch Tool" button
• Dialog to select tool type
• Instance list with status/actions
• Quick actions: start/stop/delete

State Machine

[create] -> pending -> [docker up] -> building -> [container running] -> running
                                                    |
                                                    v
                                              [docker error] -> error

[running] -> [stop] -> stopped
[stopped] -> [start] -> pending -> building -> running
[any] -> [delete] -> [docker down] -> deleted

Security

• Only repository owner can create instances
• Instances run in isolated Docker networks
• No privileged containers
• Resource limits (CPU, memory) on containers