Running a session
Start an agent on a task, watch it work, steer it, and review what it changed — all from the project workspace.
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 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.
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 for setup, and Live in Machine Desktop 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 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.
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 to land the work · Sessions for the model behind it.