--- title: Sessions description: A session is a git branch and a sandbox where the agent works. --- A session is one unit of agent work. Beeuni cuts a git branch and provisions a sandbox for it. The session id, the branch name, and the sandbox id are the same value. ## Status A session reaches one of 4 states in practice. | Status | Meaning | |---|---| | `provisioning` | Beeuni cuts the branch and requests the sandbox. | | `running` | The sandbox is live and reachable. | | `stopped` | The session is paused, by you or by idle auto-stop. | | `failed` | Provisioning failed. | The database defines 3 more values (`queued`, `branching`, `completed`). Beeuni does not write them for a session today. ## Stop, resume, and idle auto-stop You can stop a session yourself. Resume brings back the same sandbox with the same filesystem and runtime identity. Only the running processes and memory reset. The default runtime conversation remains attached to the session. Beeuni also stops an idle session for you: - After 15 minutes idle, for a normal session or a trigger run. - After 2 minutes idle, for a worker session another session started. A busy agent turn blocks the stop. The maintenance sweep runs every 5 minutes. A normal automatic Stop therefore occurs approximately 15 to 20 minutes after the terminal turn. A turn that waits on a person does no work: the agent asked a question, or asks for permission to run a tool. Such a turn keeps the computer for at most 2 hours after Beeuni first sees the wait. In a trigger or schedule run, nobody receives the ask, and the limit is 30 minutes. Beeuni then ends the turn and stops the computer. Send a message to continue. A model call or your open session page counts as activity and extends the computer as usual. A session page you are using keeps the session awake. It counts as in use while the tab is visible and you clicked, typed, scrolled or touched it in the last 10 minutes, and only when you may start sessions in the project. A tab left open with no input stops counting after 10 minutes, so the session stops about 15 to 20 minutes later. A read-only viewer's open tab never keeps it awake. Using the page alone keeps a session awake for at most 2 hours after its last agent turn; a new message starts a turn and resets that limit. ## What stop and delete keep :::warning[Deletion is permanent] Deleting a session destroys its sandbox for good. Beeuni keeps the session record and the git branch, so you can still recover pushed work. Anything not pushed is gone. ::: Stop and resume keep the sandbox's identity and filesystem. Delete destroys the sandbox. Git is the only durable record: work the agent commits and pushes survives; everything else does not. ## Labels A label classifies a session: `bug`, `customer: eu`, `worker`. Open a session's `⋯` menu and choose **Edit labels**. The **Labels** filter in the session list shows only sessions that carry every label you pick. Labels are free-form, 1–64 characters, at most 20 per session. Agents and scripts set labels too: `beeuni sessions new --label worker`, `beeuni sessions update --label needs-review` (inside a session, without an id, it labels that session), or `labels` in the API and SDK. A session also carries a free-form `metadata` object for your own keys — see SDK sessions. ## Notifications Beeuni notifies you when a session you watch ends a turn, fails, or waits on you. You watch the sessions you create and the sessions you send a message in. To stop one session's notifications, open the session menu next to its title and choose **Mute notifications**. See [Notifications](/docs/work/notifications). This needs the project's `notification_center` flag. With it off, only the session creator's phone gets a session push, and an account owner's phone gets one when a trigger starts failing. The session menu has no **Mute notifications**. See [Turn notifications on](/docs/work/notifications#turn-notifications-on). ## Runtime A session runs one harness, default runtime or experimental runtime. See [Harnesses](/docs/work/harnesses). Beeuni stores the selected agent and model when the session starts. A running session keeps its harness until it is restarted or resumed. ## Session access A session is private to the person who created it. The owner opens **Session access** and picks one of 3 options. | Option | Who can open the session | |---|---| | Only you | The owner alone. This is the default. | | Specific people | The owner, plus the members and groups the owner picks. | | Whole project | Every member of the project. | Everyone with access reads the conversation and continues it. **A shared session runs on shared keys.** Once shared, a session uses only provider keys shared with the whole project, never one person's own keys or ChatGPT connection. If its model ran on your own keys, sharing switches it to the project's keys for that provider. If the project shares no key that runs the model, sharing is refused and the session stays private. See [Provider keys and member access](/docs/project/models#provider-keys-and-member-access). **Only the owner changes this.** A project manager who did not create the session can open it once it is shared with them, and can stop, restart, or delete it. They cannot rewrite who else can open it. Sharing a session with a manager is not handing them its access list. One kind of session has no human owner: the ones a trigger creates, which run under the trigger agent's identity. Project managers govern those. Set the policy for all of them on the trigger itself, under **Session access** on the trigger — saving there also updates the sessions that trigger already created. ### Admins can open every session An account owner can let account owners and admins open **every** session in the account, including sessions members keep private. Turn it on under **Account → Settings → Security → Admins can open every session**. It is off by default. - **Only an account owner changes it.** An admin sees the switch but cannot flip it, so no admin can grant themselves access to everyone's work. - **Admins find these sessions on the project's Sessions page.** The sidebar still lists only the sessions you started or that are shared with you. - **Access is full access.** An admin opens, reads, and continues the session, the same as a session shared with the whole project. - **Members see it.** While it is on, the Session access dialog says that owners and admins can open every session. - **Everything is audited.** Each flip is recorded as `iam.session_oversight.enable` or `iam.session_oversight.disable`, and each session an admin opens through it as `project.admin_oversight_session_read` (at most once per admin and session per hour). - Agent and sandbox tokens never gain this access, even when an admin launched them. ### Find a session by owner or access The project's **Sessions** page shows each session's owner and access on its row: the owner's avatar and name (**You** for your own), then an icon for who can open it: a lock for **Only the owner**, people for **Specific people**, a globe for **Whole project**. Open **Filter** on the Sessions page to narrow the list: - **Owner** — one entry per person, with a count. - **Access** — Only the owner, Specific people, or Whole project. - **Grouping → Owner** — one section per person, yours first. The filters combine with **Status**, **Source**, and search. **Reset** clears them all. :::warning[A session keeps its owner] Removing someone from the account does not move their sessions to anyone else. Their access policy freezes as it was. A project manager can still stop or delete those sessions — deleting is the way to revoke a session nobody owns any more. ::: ## Sharing a preview You can share a session's live preview with a public link, in view-only or interactive mode. Minting that link is the session owner's call, for the same reason: the link is unauthenticated, so anyone holding the URL reads the session without signing in. A project manager can list and revoke a session's links without owning it — revoking only ever removes access. For the full status enum, injected environment variables, and daemon endpoints, see [Runtime](/docs/work/runtime). For how a session picks its agent, see [Agents](/docs/project/agents). For sessions a schedule or webhook starts, see [Triggers](/docs/connect/triggers). To land session work on the default branch, see [Change requests](/docs/work/change-requests).