Where this applies
Entry points
- The New chat button in the sidebar, or
⌘N. ⌥⌘O: opens the new chat page with No project selected.- The + that appears when you hover over a project row in the sidebar, or New task in this project on the project page: opens the new chat page with that project preselected.
⌘ with Ctrl and ⌥ with Alt (the same applies below).
Parts of the new chat page
The session starts in the project’s current working directory. The new chat page has no branch selection.
Steps
- Click New chat. The project defaults to No project.
- (Optional) Choose a project.
- (Optional) Choose a run environment: Cloud server or a device under Run on your device.
- (Optional) Adjust permissions, model, and reasoning effort.
- Write what you want done (you can also send only attachments), then press
Enterto send (Shift+Enterfor a new line). - The session appears in the sidebar. Once the session is created, you go to the session page automatically and the agent starts working.
Choose a project
Click the project button (⌥⇧⌘O) to open the menu. You can search projects, choose a project, choose New project, or choose No project. On the new chat page, you can also use ⌥⌘1–⌥⌘9 to pick projects 1–9 directly.
- Each project has a line of source text below it, such as a GitHub repository name or Local · folder name. Projects not fully set up show Setting up · not ready yet.
- You can also choose a local project on another computer; the session runs on that device. When that device is offline, it is marked Device offline.
- The new chat page does not remember the last project you chose. Each time you click New chat, it goes back to No project.
No project
A session with No project is not linked to a project. It runs in a temporary working directory, which suits Q&A, writing a script, organizing material, and similar tasks. It appears in the sidebar’s Chats group and can be moved into a project later; see Messages and session actions.Choose a run environment
The run environment determines on which machine the agent reads and writes files and runs commands. The agent itself always runs in the cloud:- The default is Cloud server. Local projects default to running on the device where the project is.
- Devices that cannot be chosen are grayed out with the reason (such as Device offline or Execution disabled).
- The run device is chosen when the session is created and cannot be changed later. To use a different device, create a new session.
Choose permissions
Permissions determine whether the agent asks you before taking actions. Click the permission button at the bottom left of the message box (Ctrl+Shift+S):
- New sessions default to Full access. Each new session starts from the default and does not remember your last choice.
- When running on a device, permissions cannot exceed the device’s permission limit, and levels above it are grayed out. Change the limit under Machines & access in the app on that device.
- You can also change permissions at any time in a session that has already started. Repair tasks and archived sessions cannot be changed.
- For how to handle requests for your approval, see Needs your input.
Confirmation for turning on full access
When running on a device and you switch to Full access, Turn on full access? appears. It explains that the agent will be able to run commands, access the internet, and create and modify any files without asking for your consent, and notes the risks such as loss or leakage of sensitive data and prompt injection (including that the agent can read all of this project’s secrets). Only clicking Confirm switches it. Clicking Cancel or pressingEsc keeps the original permission.
Choose a model and reasoning effort
The bottom right of the message box has the model button and the reasoning effort button. A new session uses your account’s default selection or your selection when you last created a session. For full details, see Harness and models.Confirmations before sending
The dialogs below appear only the first time. Clicking Cancel in any of them does not send the message, and the text and attachments stay in the message box.Full access by default (first send with full access)
The Full access by default dialog explains that the agent can run commands, install dependencies, modify files in the cloud environment, access the internet and connected services, and read all of this project’s secrets. It also notes that you can switch to Ask for approval or Approve for me at any time at the bottom left of the message box. Click Got it, start the task to send; the dialog does not appear again.Cloud server admin access (first send on the cloud server)
When cloud server admin access is turned on, the first time you start a session on the cloud server, Turn on admin access on cloud server appears and notes:- The agent has admin access on the cloud server, and credentials stored on the cloud server can be read.
- Approval and branch restrictions are only recommendations and are no longer enforced.
- Turning it off does not undo changes already made. Accidentally modifying system files may require rebuilding the cloud server.
Rules and states
For other errors, see Errors and recovery.