# Running a session

Start an agent on a task, watch it work, steer it, and review what it changed — all from the project workspace.

Canonical page: https://themachine.myapps.ai/docs/guides/running-a-session

A **session** is one agent run in its own sandbox. You describe a task, the
agent works on a private branch, and you keep the result through review. This
is the loop you'll use every day.

## Start a session

### Describe the task

Open a project and use the composer on the project home to describe what you
want — the same way you'd brief a teammate. Be specific about the goal and any
constraints; you can keep talking to the agent once it starts.

Press send and Machine boots a fresh sandbox for this session. The first boot
takes a few seconds; you'll land in the session view as soon as it's running.

### Pick a model (optional)

The model selector in the composer lets you choose which model runs the agent:
Claude, GPT, Gemini, or any other model your project offers. Pick a faster one
for quick edits and a more capable one for harder work. The default is a
sensible balance; switch any time. See [Models](/docs/project/models) for what
is available and who pays.

## Work with the agent

The session view is a conversation. The agent narrates what it's doing, and you
can **reply at any point** — answer a question, redirect it, add detail, or tell
it to try something else. You don't have to wait for it to finish.

Alongside the conversation you have:

- **Files** — browse the sandbox's working copy as the agent edits it.
- **Terminal** — see the commands it runs and their output.
- **Diff** — review the exact changes it's proposing, file by file. A badge
  shows when there are pending changes to look at.

> **Info**
> The agent works in a **private copy** of your project on its own branch.
> Nothing touches your real project until you review and merge — so let it run,
> experiment, and even make mistakes safely.

### Dictate instead of typing

The microphone button sits next to **Send** in the composer. Click it, speak,
then click the square to stop. Machine transcribes the recording and adds the
text to your message, so you can read and edit it before you send.
Right-click while recording to cancel.

Dictation works in every major browser, including Safari. A recording can run
for up to 15 minutes. The button is unavailable while the agent is in the
middle of a turn.

> **Self-hosting**
> Dictation posts the recording to `POST /v1/transcription` on your API. The
> API uses Groq Whisper when `GROQ_API_KEY` is set, otherwise OpenAI Whisper
> with `OPENAI_API_KEY`. Recordings over 25 MB are refused.

### Talk to the agent live

The **Live** button in the session header starts a voice call with the
session's agent. The call opens in a small floating window over the chat, so
you can keep reading and typing behind it. You can mute, minimize, or drag the
window. When you hang up, the whole call transcript is posted into the session,
and the agent carries on from it.

Live runs on your own Glyph account. The first time you press **Live** in a
project, it asks you to connect Glyph under the project's **Settings →
Channels**. See [Glyph](/docs/connect/glyph) for setup, and
[Live in Machine Desktop](/docs/desktop/live) for calls from the desktop app.

## Steer the run

A few controls shape how the agent works:

- **Context** — add code context, knowledge files, or a system prompt for this
  session, so the agent has what it needs without you pasting it into chat.
- **Session settings** — choose which agents, skills, and tools are available
  for the run.

These live in the session's settings; set them up front for a big task, or
adjust mid-run.

## Keep, share, or revisit

When the agent finishes a piece of work it **opens a change request** — a summary
plus the exact diff. That's your review gate; see
[Reviewing changes](/docs/guides/reviewing-changes) to merge it.

From the session's menu in the header you can also:

- **Rename** it so it's easy to find later.
- **Share** it: choose who in the project can open the session (**Whole
  team**, **Only you**, or **Select members**).
- **Export conversation** to download the transcript.
- **Summarize conversation** to compact a long transcript.
- **Stop** or **Restart** the session's sandbox.

## Coming back to a stopped session

Machine stops an idle session after about 15 minutes. When you open it again,
the conversation appears straight away from a saved copy, with a small banner
above it while the sandbox wakes. You can scroll back and read it during the
wake, and you can type and send right away: your message is queued and goes
to the agent as soon as the sandbox is up. Images, show cards, and files you
uploaded show from saved copies too.

The agent's browser also stays signed in between runs, so sites it logged in
to are still logged in after a stop.

> **Warn**
> Stopping keeps the sandbox's files; **deleting** a session destroys the
> sandbox and its saved conversation for good. Only work the agent
> **committed and pushed** to its branch survives a delete — and only a
> **merged change request** makes it part of your project. If in doubt, merge.

---

**Next:** [Reviewing changes](/docs/guides/reviewing-changes) to land the work ·
[Sessions](/docs/work/sessions) for the model behind it.