AgentContainer

Overview

Hibernation is for autonomous tasks that need to pause while they wait for something outside the container: a human approval, a webhook, a long-running external job, or a scheduled time. Instead of keeping the runtime alive and billing while it waits, the task can enter a durable hibernating state.

From the API user's point of view, a hibernating task is still the same task resource. It has not finished, its completedAt stays null, container billing is paused, and you can wake it later through the API.

When to use hibernation

Use hibernation when the next useful step depends on an external signal and you do not want to pay for an idle container.

A customer needs to approve a plan before the agent continues.
A background export, payment, or deployment webhook will arrive later.
The task should resume at a specific time, but keep all current workspace context.
An agent needs to pause a multi-step workflow without marking the task complete.

If you simply want a chat-style back-and-forth, use Conversational Tasks. If you want an autonomous task to pause and later continue from a checkpoint, use hibernation.

What the API shows

A hibernating task returns a normal task object with status: "hibernating" and hibernateUntilAt. The wake payload is intentionally not included in the top-level task response.

Hibernating task responsejson

{
  "id": "tsk_abc123",
  "status": "hibernating",
  "hibernateUntilAt": "2026-04-14T15:00:00.000Z",
  "completedAt": null,
  "error": null
}

In dashboards and API clients, treat hibernating as a paused, non-terminal state. The task is not running, not complete, and not failed. It is waiting for either an explicit wake request or its wake deadline.

Wake a task

To wake a hibernating task before its deadline, call the task wake endpoint. For v1, wake payloads are text-only: either send a non-empty message, or use external_wake for an explicit system wake without user text.

Wake with a messagebash

curl -X POST https://agentcontainer.co/api/v1/tasks/tsk_abc123/wake \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "message",
    "message": "The approval arrived. Continue and finish the report."
  }'

Wake without user textbash

curl -X POST https://agentcontainer.co/api/v1/tasks/tsk_abc123/wake \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "external_wake"
  }'

Only the first wake for the current hibernation window is accepted. That wake immediately moves the task back to pending and clears hibernateUntilAt. Later wake requests for the same window return a conflict because there is no longer a hibernating task to wake.

What happens after wake

After a wake is accepted, the task goes directly back to pending. A runner can then claim it, start a fresh container from the latest checkpoint, and continue the task as a new attempt.

The original task startedAt stays the same, while each resumed container gets its own attempt start. The accepted wake is consumed for that resumed attempt, so it will not replay again on later hibernation cycles.

Deadline wakes

If no API wake arrives before hibernateUntilAt, the scheduler wakes the task automatically with a synthetic timeout wake. The task goes directly back to pending and resumes from the checkpoint just like an API wake.

Inside the runtime

Your API integration does not call hibernate directly. Hibernation is requested by the running autonomous task from inside the workspace using /workspace/task/hibernate. This lets the agent choose the safe pause point after it has saved context and knows what signal it is waiting for.

Durable hibernation starts at 60 seconds. If the agent requests a shorter delay, the helper sleeps locally inside the current container and prints a confirmation instead of creating a checkpoint or changing the task status.

Hibernate for 5 minutesbash

/workspace/task/hibernate --timeout 300

Short waits stay localbash

/workspace/task/hibernate --timeout 30
# Sleeps locally, then prints:
# Slept for 30 seconds. No hibernation checkpoint was created.

Hibernate until a specific timebash

/workspace/task/hibernate --until 2026-04-14T15:00:00Z

For --until, timestamps less than 60 seconds away behave the same way: the helper sleeps locally until the timestamp is reached. Timestamps in the past are rejected.

Once accepted, hibernation is a terminal control for that attempt. The active agent process stops, the runner persists the checkpoint, and the host slot is freed. If checkpoint publishing fails, the task fails instead of silently losing the resumable state.

Resume context

On resume, the runtime receives a concise note prepended to /workspace/task/TASK.md. Machine-readable wake details are available to the resumed runtime through the task spec, and safe wake metadata appears in task events.

Resume notetext

## Resume Context
This task resumed from hibernation.
Source: http
Message: The approval arrived. Continue and finish the report.

Next steps

For the complete task schema, see Tasks & Output. For the request and response shape of the wake endpoint, see the API Reference.

Hibernating Tasks