> ## 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.

# Jobs & Parallel Execution

> Parallel job scheduling and the job state machine

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

```bash theme={null}
# 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

| State          | Description                                         | Next States                   |
| -------------- | --------------------------------------------------- | ----------------------------- |
| **Pending**    | Job created, queued for a worker slot               | InProgress                    |
| **InProgress** | Worker actively running — LLM calls, tool execution | Completed, Failed, Stuck      |
| **Completed**  | Job finished successfully                           | — (terminal)                  |
| **Failed**     | Unrecoverable error or explicit cancellation        | — (terminal)                  |
| **Stuck**      | No progress detected within timeout window          | InProgress (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 Variable     | Default | Description                          |
| ------------------- | ------- | ------------------------------------ |
| `MAX_PARALLEL_JOBS` | `5`     | Maximum 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.

<Note>
  Increasing `MAX_PARALLEL_JOBS` increases LLM API concurrency. Set it according to your API rate limits and available system resources.
</Note>

***

## Job Tools

Four built-in tools let the agent manage jobs at runtime:

| Tool         | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `create_job` | Create a new job with a given description and optional context |
| `list_jobs`  | List all active jobs with their current state and metadata     |
| `job_status` | Get detailed status for a specific job by ID                   |
| `cancel_job` | Cancel an InProgress or Pending job                            |