Documentation Index Fetch the complete documentation index at: https://docs.namastex.ai/llms.txt
Use this file to discover all available pages before exploring further.
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/containersGet Container Info Get detailed information about a worktree container.
Path Parameters
Parameter Type Description idstring Container/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
Field Type Description idstring Container ID taskAttemptIdstring Associated task attempt worktreePathstring Absolute path to worktree branchstring Worktree branch name baseBranchstring Target branch for merge statusenum active, inactive, merged, deletedcreatedAtstring Creation timestamp diskUsageobject Disk space information gitStatusobject Git status summary filesobject File 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
Attempts API Task attempts using containers
Git Worktrees Learn about worktree isolation
