Skip to main content
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
Reusing a session runs the task in an already-open environment. This is faster and preserves any state from previous tasks.

​
Staying logged in across sessions

Sessions always start from a clean environment, so a new session normally means a fresh login. If the credential has credential persistence enabled, Deck restores the credential’s saved login state into the new session, and the agent can pick up already logged in when the source honors it. This is a credential setting, not a session one: the session lifecycle described on this page is unchanged.

​
Session statuses

​
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

This requests teardown of the agent sandbox. The session doesn’t close instantly: it transitions to completing and then to completed once teardown finishes. Any running task runs in the session are canceled as part of teardown. You can only end a session that is queued, running, or idle. Ending a session that has already finished (completed or failed) returns an error.

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