Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.deck.co/llms.txt

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

A session is an isolated compute environment where Deck executes tasks. Sessions are created automatically when you run a task, or you can reuse an existing session to run multiple tasks in the same environment.

​
How sessions fit in

When you run a task, Deck creates a session (or reuses one you specify) and executes the work. The session manages the compute lifecycle so your application doesn’t have to.

​
Session lifecycle

Sessions are created implicitly when a task runs. You don’t need to create them ahead of time. The response includes a session_id you can reuse.

​
Reusing a session

To run additional tasks in the same session, pass the session_id from a previous task run: POST /v2/tasks/{task_id}/run 
{
  "session_id": "sess_x9y8z7...",
  "input": {
    "check_in_date": "2026-05-01"
  }
}
Reusing a session runs the task in an already-open environment. This is faster and preserves any state from previous tasks.

​
Session statuses

StatusMeaning
queuedWaiting to be provisioned
runningActive and executing work
idleNo active tasks, waiting for new work
completingWork is done, session is shutting down
completedAll work finished and the session was closed
failedThe session encountered an error

​
Timeout

Sessions time out after 10 minutes of inactivity. Inactivity means no task runs are executing in the session. When the timeout elapses, the session is torn down automatically and transitions to completed. To keep a session alive across multiple tasks, start the next run before the 10-minute window elapses.

​
Ending a session

POST /v2/sessions/{session_id}/end
This tears down the agent sandbox and transitions the session to completed. Any running task runs in the session will be canceled.

​
When to reuse sessions

Reuse a session when you need to run multiple tasks for the same user in quick succession. A common pattern is to run a task and then immediately follow up with related tasks in the same session.