# Browser sessions

A session is a browser your agent starts for a task. Keep related pages in tabs of the same
session, and stop the session when the task is finished.

## Mobile layouts

Websites open in their mobile layouts in a session. The agent taps, swipes, and types on them
as a person would.

If a website only works in its desktop version, give the agent the
[Change browser settings](agents.md#choose-page-permissions) permission. It can then turn on
Desktop site for a tab, which asks websites for their desktop version.

## Start and reuse a session

Your agent starts a browser with `browser_session` and `action: "start"`. The reply gives a
`session_id` and, once ready, the first tab's `page_id`. Browser tools use these IDs to act on
the right session and tab.

If startup returns `state: "starting"`, repeat start with the same label after a few seconds.
Rukou returns the existing session. Keep that label stable during retries so the agent does
not create extra browsers.

Use `browser_tabs` to open, list, and close tabs. Tabs keep loading while the agent works in
another tab, but calls on one session run one at a time. Independent agents working in
parallel should use their own sessions, within the organization's concurrency limit.

## Watch or take control

Open **Sessions**, select the session, and choose the tab you need. Select **Take control**
to interact with it yourself. When finished, select **Release**. The agent should read the
page again before continuing because your actions may have changed it.

An agent can use `browser_request_help` for a code, a choice, or another step that needs you.
The session page highlights the request. Open it, take control, complete the step, and release
control. Calls on the affected tab wait while it needs help; the tool's reply explains the
scope of the hold for that session.

An organization owner or admin can use **Release teammate** when another person holds control
and cannot release it themselves.

## Time limits

`rukou_status` shows how long a session runs before it needs an extension and how long it may
sit idle. A session's reply gives its deadline, the time remaining, and the latest time that
extensions can reach.

An agent can extend a running session with `browser_session`, `action: "extend"`, before time
runs out. An extension cannot pass that latest time, and it does not remove the idle timeout.
Sessions can end because of time, inactivity, or access changes as well as an explicit stop.

## Reuse a persona

A session's browser has a persona: the visitor that websites see, with its own fingerprint.
An agent normally starts with its own persona. To choose one, give start a `seed`, such as
`research-1`. The same seed within a workspace selects the same persona and fingerprint,
including when another agent in that workspace uses it.

A seed is a non-secret label. It does not preserve tabs or cookies. To reuse an approved
login's signed-in state, use [saved sign-ins](logins.md#keep-a-sign-in-for-another-session).

## Stop and replay

Ask the agent to call `browser_session` with `action: "stop"`, or choose **Stop session** from
the session menu. The browser, its tabs, and its cookies are discarded. Stopping does not save
sign-ins automatically, and an ended browser cannot be resumed.

When a recording is available, the session offers **Replay** or **Play recording**. Use the
timeline to inspect what happened. The page shows how long the recording is kept. An expired,
deleted, or unavailable recording cannot be replayed. Replay is a view of the past session;
start a new browser to continue the task.

If you delete a recording, its trace is deleted too.