Skip to main content

Overview

The Containers API provides information about git worktree containers used by task attempts. Each container represents an isolated workspace where AI agents execute tasks. Base URL: http://localhost:8887/api/containers

Get Container Info

Get detailed information about a worktree container.
GET /api/containers/:id

Path Parameters

ParameterTypeDescription
idstringContainer/worktree ID

Example Response

{
  "success": true,
  "data": {
    "id": "container_abc123",
    "taskAttemptId": "attempt_xyz789",
    "worktreePath": "/path/to/.forge/worktrees/task-abc123-attempt-1",
    "branch": "forge/task-abc123-attempt-1",
    "baseBranch": "main",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00Z",
    "diskUsage": {
      "total": 52428800,
      "used": 15728640,
      "available": 36700160
    },
    "gitStatus": {
      "ahead": 3,
      "behind": 0,
      "modified": 2,
      "untracked": 1,
      "conflicted": 0
    },
    "files": {
      "total": 156,
      "modified": 8,
      "added": 3,
      "deleted": 1
    }
  }
}

Response Fields

FieldTypeDescription
idstringContainer ID
taskAttemptIdstringAssociated task attempt
worktreePathstringAbsolute path to worktree
branchstringWorktree branch name
baseBranchstringTarget branch for merge
statusenumactive, inactive, merged, deleted
createdAtstringCreation timestamp
diskUsageobjectDisk space information
gitStatusobjectGit status summary
filesobjectFile statistics

Use Cases

Monitor Disk Usage

Track worktree disk usage to prevent space issues:
const container = await forge.containers.get('container_abc123');

if (container.diskUsage.available < 1000000000) { // < 1GB
  console.warn('Low disk space in worktree');
}

Check Git Status

Verify worktree state before merging:
const container = await forge.containers.get('container_abc123');

if (container.gitStatus.conflicted > 0) {
  console.error('Container has merge conflicts');
} else if (container.gitStatus.modified === 0) {
  console.log('No changes in worktree');
}

SDK Examples

JavaScript/TypeScript

import { ForgeClient } from '@automagik/forge-sdk';

const forge = new ForgeClient();

// Get container info
const container = await forge.containers.get('container_abc123');

console.log('Worktree path:', container.worktreePath);
console.log('Modified files:', container.files.modified);
console.log('Disk usage:', container.diskUsage.used / 1024 / 1024, 'MB');

Python

from automagik_forge import ForgeClient

forge = ForgeClient()

# Get container info
container = forge.containers.get('container_abc123')

print(f"Worktree: {container['worktreePath']}")
print(f"Modified: {container['files']['modified']} files")

Next Steps