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.

Interactive container list and detail responses omit launch environment-variable values (envVars / env_vars), including for the creator. Terminal and CLI clients use the container's identifiers, environment, status, and default agent; the launch settings remain available internally to run the container.

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

Configure the standard threshold in Server Settings → General → Container Inactivity (hours) (container_cleanup_hours), or override it with CONTAINER_CLEANUP_HOURS on the server. Pinned containers use a fixed 48-hour inactivity threshold; pinning does not prevent stopping or removal.

Optional Post-Turn Idle Threshold

Set idle_container_cleanup_hours in the server setup configuration, or IDLE_CONTAINER_CLEANUP_HOURS in the server environment, to stop non-pinned containers sooner after a turn finishes. This optional setting has no field in the Settings UI. When unset, the standard inactivity threshold applies.

The shorter threshold applies only when the task has finished a turn, is not an interactive task, and has no attached terminal or active App Server session. It only takes effect when shorter than the standard threshold. Pinned containers still use 48 hours.

What Counts as Activity

Cleanup uses the most recent recorded container/agent activity, turn completion, or task creation time. Starting a follow-up, restarting the container, or opening a browser terminal records fresh container activity. An attached browser terminal or an active App Server session prevents automatic stopping under either inactivity threshold.

Task-board changes such as pinning, snoozing, or approval do not extend retention. Merely viewing a task is not a reliable way to keep its container alive: cleanup uses dedicated container activity timestamps when available, with older task activity metadata as a compatibility fallback.

If a manual Stop Container request fails, CoderFlow shows a fixed failure message without service details. Refresh the task to check the container's current state before making another explicit stop attempt.

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)

The same 10-minute cleanup sweep removes eligible stopped task containers. Automatic removal applies to tasks in a terminal state: completed, failed, interrupted, ended, or rejected. Active and queued tasks are not eligible for removal by this sweep.

Removal Reason	Behavior
Approved and pushed	A stopped container is eligible once the task's approval records a successful push. It does not need to reach the retention limit.
Marked as loser	A stopped container is eligible once its task variant is marked as a loser. It does not need to reach the retention limit.
Retention expired	A stopped container is eligible after 7 days by default, even if the task is unapproved or pinned.
Rejected	Explicit task rejection (for example, through the CLI) immediately attempts to stop and remove the container. If removal fails, the stopped container can later qualify for the sweep under the rules above.

Configure Server Settings → General → Stopped Container Retention (days) (stopped_container_retention_days), or override it with STOPPED_CONTAINER_RETENTION_DAYS. The retention window starts from the latest recorded container stop, turn completion, or container activity timestamp, rather than the task's creation date. A container newly stopped by cleanup gets a fresh retention window, unless approval/push or loser status makes it eligible earlier.

Protect Container

On the task page, choose More actions → Protect container to exempt an existing container from all automatic removal policies, including removal after approval/push, loser selection, and retention expiry. Choose Remove container protection in the same menu to allow automatic removal again. This per-task setting is stored as task.containerProtected; the API is PATCH /tasks/:id/container-protection with {"protected": true} or {"protected": false}.

Protect container is the only explicit per-task exemption from automatic removal. It does not prevent inactivity stopping. Explicit actions such as rejection, task deletion, Remove Stopped Containers, or manual Docker System Prune can still remove the container.

Pinning and Snoozing

Pinning keeps a task in view and gives its running container a 48-hour inactivity grace. Only the task creator's own pin does this: a pin someone keeps on another person's task puts it on their own list without changing the container's thresholds. Pinning does not exempt a stopped container from removal. Snoozing a pin changes task-board visibility; the task remains pinned and follows the same stop and removal policies while snoozed. Use Protect container when you need to preserve the existing container for later review or QA.

For compatibility, already-stopped pinned containers without a recorded stop timestamp receive a one-time 7-day grace when cleanup first encounters them as removal candidates. The deadline is saved across server restarts so owners can enable protection. This is a migration grace, not indefinite retention or an extra week for every pinned container.

Scheduled Follow-ups

While a task has scheduled follow-ups, including a wake-up a task scheduled for itself, its stopped container is not removed automatically, whatever the removal reason. Inactivity stopping still applies: nothing runs while the follow-up waits, and its delivery starts the stopped container again. The hold lasts until every scheduled follow-up has been sent or removed. That includes one whose time has come but which is still waiting in the follow-up queue, for example behind a queue on hold after a failed or interrupted turn. Follow-ups can be scheduled at most 30 days ahead. Scheduling and automatic removal never overlap: a schedule being saved defers the removal to a later sweep, and a follow-up cannot be scheduled while the container is being stopped or removed. Explicit removal actions are unaffected.

What Happens to My Task When Its Container Is Removed?

Container removal preserves the task's saved history, logs, output, and diffs. After retention cleanup, the task page shows “Task container removed after N days of inactivity”. Use Continue in New Container to fork the task into a new container; full history replay is selected by default. The old container cannot be restarted, and unsaved state that existed only inside it cannot be recovered. Deleting the task itself or explicitly requesting task-data cleanup is separate from container removal.

Automatic Docker storage prune never removes containers. Task containers are handled by the lifecycle sweep described here; manual cleanup actions have broader scope. See Server Monitoring → Cleanup Operations.

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 lifecycle of the container they belong to, not of one run of it:

Event	What Happens
Container first 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, then started again	The library is kept, with the objects built into it, and reused when the container starts again.
Container is removed	The CoderFlow server deletes the library (DROP SCHEMA CASCADE) over the IBM i connection.

Because the library is deleted only after the container is removed, a task library lasts as long as its container. Stopping an inactive container keeps the library; the container's removal (see Automatic Removal above) deletes it.

Orphaned Libraries

A failed deletion is retried with a growing wait, up to CODERFLOW_EXTERNAL_RESOURCE_MAX_ATTEMPTS attempts (default 10, about a day). After the last attempt, or at once when the deletion cannot run at all (for example, the connection was deleted), the library is marked orphaned: the server logs an error naming it and does not try again. The most common cause is an IBM i job holding a lock on an object in the library.

Orphaned libraries can be identified from that error or 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. See IBM i Task Libraries for details.

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 — inactivity exceeds the configured threshold (2 hours by default, 48 hours if pinned, or the optional shorter post-turn threshold); container can be restarted
3. Removed — eligible stopped container is approved+pushed, marked as loser, or past retention without protection or a pending scheduled follow-up; explicit rejection also attempts removal. Saved task history remains available for continuation in a new container

Configuration Reference

Valid environment overrides take precedence over the corresponding server setup settings. The sweep reads the effective settings each cycle.

Setup Setting	Environment Override	Default	UI Location and Meaning
container_cleanup_hours	CONTAINER_CLEANUP_HOURS	2 hours	Server Settings → General → Container Inactivity (hours). Standard non-pinned inactivity threshold; minimum 0.1 hour.
stopped_container_retention_days	STOPPED_CONTAINER_RETENTION_DAYS	7 days	Server Settings → General → Stopped Container Retention (days). Retention for eligible stopped containers, including pinned tasks; minimum 1 day.
idle_container_cleanup_hours	IDLE_CONTAINER_CLEANUP_HOURS	Unset (standard threshold)	Setup/environment only. Optional shorter post-turn inactivity threshold for non-pinned, non-interactive tasks without attached sessions; minimum 0.1 hour when set.

Invalid standard inactivity or retention overrides fall back to the valid setup value, then the default. An invalid idle override disables the optional shorter threshold, so the standard threshold applies to non-pinned containers.

Protect container is a per-task option in More actions, not a server-wide setting or environment variable. The pinned 48-hour stop threshold, one-time legacy 7-day grace, and 10-minute sweep interval are not exposed as configurable settings.