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. You can also start one yourself with POST /v2/sessions, then pass its session_id to a task or workflow run. See Preparing a session.

​
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. The run request still requires a credential_id or source_id; the session doesn’t supply them. Runs in a session against the same source must use the same credential. To run against that source with a different credential, start a new session.

​
Preparing a session

To cut latency on the first run, start the session before your user is ready and pass a source_id: POST /v2/sessions
Deck starts the session and sends the agent to that source’s login page. When the user submits their credentials, run the task or workflow with the returned session_id, and the agent can start the login from there. A workflow run ends the session when it finishes. The session object includes source_id when one was passed. An unknown source_id returns source_not_found. source_id is a hint, not a constraint:
  • A run on the session can target any source. If it targets a different one, it still runs in the prepared session and the agent navigates to the run’s source. The session’s source_id stays as passed.
  • The run still requires its own credential_id or source_id.
  • A prepared session counts toward your organization’s session limit, and follows the same timeout as any other. If no run arrives within 10 minutes, it closes. End it if your user leaves before running anything.

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