---
title: "Sessions"
description: "Start, pause, restore and organize agent sessions on Beeuni Computer."
---

A session keeps an agent’s conversation and work together on an isolated Computer. For projects with repository access, Beeuni creates a session branch from `base_ref`, which defaults to the project’s default branch. The Computer’s filesystem and the saved conversation have different lifetimes.

<a id="status"></a>

## Status

| Status | Meaning |
| --- | --- |
| `provisioning` | Preparing the session and its Computer. |
| `running` | The Computer is reachable; the agent can be working or idle. |
| `stopped` | The Computer is stopped. A new message or a preview request can wake it. |
| `failed` | The Computer could not start. Read the error on the session page. |

<a id="stop-resume-and-delete"></a>

## Stop, resume and delete

| Action | Command | Result |
| --- | --- | --- |
| `stop` | `beeuni sessions stop <session_id>` | Stops the Computer and the active turn. Keeps its disk, branch and conversation. |
| `start` | `beeuni sessions start <session_id>` | Starts the stopped Computer. Processes restart; the filesystem remains. |
| `rm` | `beeuni sessions rm <session_id>` | Removes the Computer and public links. Keeps the pushed branch; the conversation and stored files remain restorable for 30 days. |
| `restore` | `beeuni sessions restore <session_id>` | Returns a deleted session to the list, stopped. The next start creates a new Computer. |
| `recover` | `beeuni sessions recover <session_id>` | Prepares a lost session to continue on a new Computer from its branch and saved conversation. |

The composer’s **Stop** button ends the active turn and holds queued messages; it does not stop the Computer. A new message releases the hold. In a shared session, only the person who started the turn, the session owner or a project manager can stop it.

<a id="restore-a-deleted-session"></a>

## Restore a deleted session

After deleting one session in the web app, choose **Undo** in the confirmation toast. You can also open **Recently deleted** from the Sessions page or the session menu in the sidebar. This list includes your deleted sessions and sessions you can manage as a project manager; restore each one before its 30-day deadline. `beeuni sessions rm` prints the restore command and deadline; the API returns `restore_until`. Restore requires the session owner or a project manager. If removal is still pending, wait and retry.

Restore recovers the conversation, stored attachments and branch, not the deleted Computer’s disk. Uncommitted or unpushed changes are lost. Revoked public links stay revoked. After 30 days, restore is no longer available.

<a id="continue-a-lost-session"></a>

## Continue a lost session

If the Computer was lost, the session page offers **Continue session**. Beeuni creates a new Computer from the session branch and loads the saved conversation. From the CLI, recover first, then start. This requires the session owner or a project manager. If no saved conversation exists, start a new session.

```bash
beeuni sessions recover <session_id>
beeuni sessions start <session_id> --wait
```

<a id="when-the-sandbox-stops-during-a-turn"></a>

## When a turn is interrupted

After an unexpected stop, Beeuni retries an unanswered message or adds a continuation for an unfinished answer. In an interactive session, it holds the message until the Computer wakes or you choose **Resume**. Automated and child sessions can resume automatically, subject to retry limits. An intentional stop, idle stop or model change does not trigger this recovery. Recovery cannot restore unsaved files; some runtimes must repeat the original message.

<a id="when-a-session-sleeps"></a>

## When a session sleeps

An idle session normally stops 15–20 minutes after its last turn. A child session becomes eligible after 2 minutes. Running turns keep the Computer awake. A turn waiting for your response can wait for up to 2 hours; trigger, schedule and system sessions have a 30-minute limit. Send a message to continue after that limit.

Using the session page keeps it awake while the tab is visible and you interacted in the last 10 minutes. This requires permission to start sessions and lasts at most 2 hours after the last turn. Signed-in preview traffic keeps the Computer awake for 30 minutes after the last request. The composer shows the page’s remaining awake time when relevant. Reading saved messages alone does not wake a stopped Computer.

<a id="pin-and-archive"></a>

## Pin and archive

Use the session’s **⋯** menu to pin or archive it. Pins appear at the top of your list; archived sessions appear in the **Archived** view. These choices affect only your list. They do not stop the session or change another member’s view. Archiving unpins a session; pinning unarchives it. Only a person, including through a personal access token, can change these preferences.

```bash
beeuni sessions pin <session_id>
beeuni sessions archive <session_id>
beeuni sessions ls --archived
beeuni sessions unarchive <session_id>
```

<a id="read-a-session"></a>

## Read the session log

`beeuni sessions log` reads saved messages without waking a stopped Computer. A running session can include the current turn. `--json` includes the session record, threads and messages; use the SDK’s session log and event stream for your own interface. Attachments saved from earlier turns remain available while the session is stopped.

```bash
beeuni sessions log <session_id> --limit 20
beeuni sessions log <session_id> --json
```

See [Sessions from code](/docs/sdk/sessions) for logs, events, restore and recovery.

<a id="labels"></a>

## 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: OpenCode or pi. 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 can read the conversation and continue 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. Only the owner can change who else has access.

Sessions created by triggers run under the trigger agent's identity and have no
human owner. Project managers control their access. 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. Only the session owner can create the link: anyone with the
URL can read the session without signing in. A project manager can list and
revoke a session's links without owning the session.

See the runtime reference for session details. [Runtime](/docs/work/runtime)

## Mention files, agents and sessions

Type `@` in the composer to reference a file, agent or session, and `/` to run a command. References also work in command arguments. A new chat lists agents first; files become available once its Computer is running.