headquarter/docs/api/config-profiles.md

Config Profiles

Overview

Config profiles allow users to define reusable configuration sets for tool instances. Profiles can include environment variables, files, mounts, and git repository mounts. They support profile includes for composition and can be scoped to specific projects or tool types.

Git Mounts

Git mounts allow you to mount files or directories from git repositories into tool instances at startup.

Git Mount Object

{
  "repo_id": "550e8400-e29b-41d4-a716-446655440000",
  "source_path": ".",
  "target_path": "/app/config",
  "branch": "main"
}

Fields:

Field	Type	Required	Description
repo_id	string (UUID)	Yes	ID of the git repository to mount from
source_path	string	No	Path within the repository (default: "."). Supports glob patterns like "*.json" or "configs/**"
target_path	string	Yes	Absolute path inside the container where files will be mounted
branch	string	No	Branch or tag to checkout before mounting (default: current branch)

Path Validation

• source_path: Must be relative (no leading /). Cannot contain .. (path traversal)
• target_path: Must be absolute (starts with /). Cannot contain ..

Glob Patterns

The source_path supports standard glob patterns:

• *.json - Match all JSON files in root
• configs/** - Match all files in configs directory recursively
• src/*.py - Match all Python files in src directory
• . - Mount entire repository (default)

Limits:

• Maximum 100 matches per glob pattern
• Only matches within the repository boundary

Branch Behavior

When a branch is specified:

1. System attempts to checkout the branch in the existing clone
2. If branch doesn't exist locally, attempts to fetch from remote and checkout
3. If checkout fails, logs warning and continues with current branch
4. No branch specified: uses current checked-out branch

Auto-clone: If repository is not cloned locally, the system will automatically clone it using the repository's configured SSH key.

Endpoints

List Config Profiles

GET /config-profiles

Query parameters:

• project_id (optional): Filter by project compatibility
• tool_type_id (optional): Filter by tool type compatibility

Response includes git_mounts array in each profile.

Create Config Profile

POST /config-profiles

Request body:

{
  "name": "My Profile",
  "git_mounts": [
    {
      "repo_id": "550e8400-e29b-41d4-a716-446655440000",
      "source_path": "configs/*.json",
      "target_path": "/app/config",
      "branch": "main"
    }
  ]
}

Validation:

• All referenced repositories must exist
• Repositories must belong to the same project (if profile has project_id)
• source_path and target_path must pass path validation

Update Config Profile

PUT /config-profiles/{id}

Same request body as create. Partial updates supported (omit fields to keep current values).

Preview Resolved Profile

GET /config-profiles/{id}/preview

Returns the fully resolved profile with all includes merged. Git mounts from included profiles are merged with override rules (later profiles override earlier ones with same repo_id + target_path combo).

Response:

{
  "profile_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile_name": "My Profile",
  "env_vars": {},
  "runtime_hints": {},
  "mounts": [],
  "git_mounts": [
    {
      "repo_id": "550e8400-e29b-41d4-a716-446655440000",
      "source_path": "configs/*.json",
      "target_path": "/app/config",
      "branch": "main"
    }
  ],
  "files": {},
  "overrides": {
    "env_vars": {},
    "runtime_hints": {},
    "files": {},
    "mounts": {}
  },
  "included_profiles": []
}

Error Handling

Git mount errors during instance startup are non-blocking:

• Missing repository: Mount skipped, warning logged
• Clone failure: Mount skipped, warning logged
• Invalid paths: Mount skipped, warning logged
• Branch checkout failure: Falls back to current branch, warning logged

Instance startup continues normally even if some git mounts fail.

Profile Resolution

When a profile includes other profiles, git mounts are merged:

• Same repo_id + target_path combo: later profile overrides
• Different combos: both are kept
• Branch conflicts: later profile wins

Example:

Base Profile:     git_mounts = [{repo_a, /app, main}]
Included Profile: git_mounts = [{repo_a, /app, develop}, {repo_b, /data}]
Resolved:         git_mounts = [{repo_a, /app, develop}, {repo_b, /data}]