# Sessions

A session is a git branch and a sandbox where the agent works.

Canonical page: https://themachine.myapps.ai/docs/work/sessions

A session is one unit of agent work. Machine 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` | Machine 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`).
Machine 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 OpenCode conversation remains attached to the session.

Machine also stops an idle session for you:

- After 15 minutes idle, for a normal session.
- After 5 minutes idle, for a session a trigger started.

An open dashboard tab does not keep a session alive. 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.

Self-host operators can set `KORTIX_SANDBOX_AUTOSTOP_MINUTES` to change the
normal idle grace. This setting does not change active-turn protection.

## What stop and delete keep

> **Deletion is permanent**
> Deleting a session destroys its sandbox for good, and purges its saved
> conversation history and saved attachments. Machine keeps the session record
> and the git branch, so you can still recover pushed work. Anything not pushed
> is gone.

| What | After stop | After delete |
|---|---|---|
| Files on the sandbox's disk | Kept | Gone |
| The agent's browser sign-ins | Kept | Gone |
| Running processes and memory | Reset | Gone |
| Saved conversation history and attachments | Kept, readable at once | Purged |
| Commits pushed to the session branch | Kept | Kept |

For your code, git is the durable record: work the agent commits and pushes
survives a delete, and a merged [change request](/docs/work/change-requests)
makes it part of the project.

### Saved conversation history

While a sandbox runs, Machine saves a copy of the session's conversation on
the server: at the end of every agent turn, and once more when the session
stops. When you open a stopped or waking session, the conversation appears
right away from that saved copy. Opening it still wakes the sandbox.

- **A small banner, not a loading screen.** While the sandbox wakes, a status
  banner above the conversation shows the boot steps (**Reserving your
  computer**, **Loading your workspace**, **Waking the agent**,
  **Connecting**). You can scroll and read the whole time. If nothing will wake
  the sandbox on its own, the banner reads **Computer stopped** and offers
  **Restart**. A brand-new session has no saved conversation yet, so its first
  start still shows the full loading screen.
- **You can send while it wakes.** The composer stays live and says
  "Waking this session up… messages you send will be queued and go out
  automatically." Queued messages go to the agent as soon as the sandbox
  answers.
- **Files still show.** Images, show cards (including CSV and spreadsheet
  previews), and files you uploaded are saved with the conversation, so they
  render while the sandbox is off. HTML previews still need the running
  sandbox.

The saved copy is the conversation only. It does not save your code; that
still lives on the sandbox's disk until the agent commits and pushes it.

Self-host operators can turn saving off with `TRANSCRIPT_HISTORY_ENABLED=false`
on the API service. It defaults to `true`. With it off, Machine stops saving new
history, and history it already saved is still served.

### The agent's browser stays signed in

The browser the agent drives saves its cookies and local storage on the
sandbox's own disk, and restores them the next time it launches. A site the
agent signed in to stays signed in after the session stops and resumes, so you
do not have to sign it in again on every run. Deleting the session removes the
saved sign-ins along with the sandbox.

## Runtime

Every session uses OpenCode REST. Machine stores the selected OpenCode agent and
model when the session starts. Restart and resume keep the same session runtime.

## Sharing a preview

You can share a session's live preview with a public link, in view-only or
interactive mode.

## Providers

Machine runs sessions on Daytona, Platinum, or E2B Cloud. A project follows
the platform default, or requests a provider switch through the SDK — see
[SDK reference](/docs/sdk/reference). A switch to a different provider is
durable: the current provider keeps serving while the target warms, then
activates. Every provider runs the same sandbox image.

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