---
sidebar_position: 4
---
# Container Lifecycle

CoderFlow automatically manages the lifecycle of task containers to balance resource usage with availability. Containers progress through several phases—from creation to eventual removal—based on activity, task status, and configuration.

## Container States

A task container can be in one of these states:

| State | Description |
|-------|-------------|
| **Running** | Container is active. The agent may be executing, or the task may be completed but the container kept available for interaction (terminal access, file browsing, app server testing). |
| **Stopped** | Container has been stopped due to inactivity but still exists on disk. It can be restarted if needed. |
| **Removed** | Container has been permanently deleted. The task's data (logs, output, diffs) is preserved, but the container environment is gone. |

## Automatic Sleep (Stopping Inactive Containers)

CoderFlow runs a cleanup job every **10 minutes** that checks for containers with no recent activity. When a container exceeds the inactivity threshold, it is gracefully stopped.

### Inactivity Thresholds

| Container Type | Default Threshold |
|----------------|-------------------|
| Standard containers | **2 hours** |
| Pinned containers | **48 hours** |

The standard threshold can be configured by setting the `CONTAINER_CLEANUP_HOURS` environment variable on the CoderFlow server.

### What Counts as Activity

The inactivity timer resets whenever a user or the system interacts with the task:

- **Viewing the task** in the Web UI
- **Opening a terminal** session to the container
- **Providing feedback** or starting a follow-up agent run
- **Approving** the task
- **Pinning or unpinning** the task
- **Changing winner/loser status** on a variant
- **Agent execution** finishing (timer starts from completion time)

If none of these interactions occur within the threshold period, the container is stopped.

### Stopped Containers Are Not Lost

Stopping a container does **not** delete the task's work. All code changes, logs, and output remain intact. The container can be restarted for further interaction—such as reviewing files, running terminals, or providing additional feedback.

## Automatic Removal (Deleting Containers)

Stopped containers are only removed when it is safe to do so—meaning no work will be lost. The same cleanup job that stops inactive containers also checks stopped containers for removal eligibility.

A stopped container is removed when **any** of these conditions are met:

| Condition | What It Means |
|-----------|---------------|
| **Approved and pushed** | The task was approved and its changes were successfully pushed to the remote repository. The code is safely stored in Git. |
| **Marked as loser** | The task variant was explicitly marked as a loser during winner selection. The user has decided this variant's changes should be discarded. |
| **Rejected** | The task was rejected via the CLI. Rejection immediately stops and removes the container. |

### Containers That Are Never Auto-Removed

**Pinned containers** are never automatically stopped or removed, regardless of inactivity. They are preserved indefinitely for demos, reference, or ongoing work. To free resources from a pinned container, you must first unpin the task.

## IBM i Task Libraries

When an environment has an IBM i connection with the Build feature enabled, CoderFlow creates a **temporary task library** (DB2 schema) on the IBM i system for each task. This library provides an isolated build environment so that tasks do not interfere with each other or with production libraries.

### Lifecycle

Task libraries follow the same lifecycle as the container they belong to:

| Event | What Happens |
|-------|-------------|
| **Task starts** | A uniquely named library is created on the IBM i system (e.g., `AITSK_ABC123...`) and added to the job's library list. |
| **Container is stopped** | The library is automatically deleted (`DROP SCHEMA CASCADE`) as part of the container's shutdown cleanup. |

Because library cleanup runs when the container stops, **task libraries persist for as long as the container is running**—up to **2 hours** of inactivity for standard containers, or **48 hours** for pinned containers (see [Inactivity Thresholds](#inactivity-thresholds) above).

### Orphaned Libraries

In some cases, a task library may not be cleaned up automatically:

- **Container crash** — if the container is terminated abruptly (e.g., the Docker host crashes) without running its shutdown handler, the cleanup script never executes.
- **Object locks** — if an IBM i job still holds a lock on an object in the library at shutdown time, the `DROP SCHEMA CASCADE` will fail. The error is logged but the container shutdown continues, leaving the library behind.

Orphaned libraries can be identified by their description text, which includes the CoderFlow task ID (e.g., `CoderFlow task 1711484523456-k7f2xm9`). They can be safely deleted manually using `DLTLIB` once any locks are released.

## Orphaned Directory Cleanup

Task directories that have no associated `task.json` file (orphaned data from interrupted container creation or other edge cases) are automatically deleted after **24 hours**.

## Summary

1. **Running** — container is active; activity resets the inactivity timer
2. **Stopped** — no activity for 2h (48h if pinned); container can be restarted
3. **Removed** — approved+pushed or marked as loser; task data preserved, container gone

## Configuration Reference

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `CONTAINER_CLEANUP_HOURS` | `2` | Hours of inactivity before a standard (non-pinned) container is stopped |

Pinned container thresholds and the cleanup check interval are not currently configurable.
