Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt

Use this file to discover all available pages before exploring further.

Every unit of work in IronClaw is a job. Jobs run in parallel, each with isolated context, and each progressing through a defined state machine until they complete, fail, or get recovered.

​
Configuration

# Maximum parallel jobs
MAX_PARALLEL_JOBS=5

# Sandbox timeout (affects when jobs are considered stuck)
SANDBOX_TIMEOUT_SECS=1800

​
Job State Machine

Pending
    ↓
InProgress ──────────────┬──► Completed
    ↑                    │
    │  (self-repair)     └──► Failed
    │
  Stuck ────────────────────► Failed (if unrecoverable)

​
States

StateDescriptionNext States
PendingJob created, queued for a worker slotInProgress
InProgressWorker actively running — LLM calls, tool executionCompleted, Failed, Stuck
CompletedJob finished successfully— (terminal)
FailedUnrecoverable error or explicit cancellation— (terminal)
StuckNo progress detected within timeout windowInProgress (recovery), Failed

​
Transitions

A job enters Stuck when the self-repair system detects it has been InProgress with no activity for longer than the configured timeout. The system then attempts recovery by re-entering InProgress with a fresh worker. If recovery fails repeatedly, the job transitions to Failed.

​
Parallel Execution

IronClaw runs multiple jobs concurrently. Each job has its own isolated context — memory, tool call history, and conversation state.
Config VariableDefaultDescription
MAX_PARALLEL_JOBS5Maximum concurrent jobs per instance
When all job slots are occupied, new jobs queue as Pending until a slot opens. The scheduler dispatches queued jobs in order of creation time.
Increasing MAX_PARALLEL_JOBS increases LLM API concurrency. Set it according to your API rate limits and available system resources.

​
Job Tools

Four built-in tools let the agent manage jobs at runtime:
ToolDescription
create_jobCreate a new job with a given description and optional context
list_jobsList all active jobs with their current state and metadata
job_statusGet detailed status for a specific job by ID
cancel_jobCancel an InProgress or Pending job