Skip to main content
A session is the unit of work in Palette Desktop. It’s what makes it safe to share a workspace with your team. Watch the video

​
What a session is

When you start a session, Palette Desktop creates a clone of your workspace. The agent works inside the clone. Nothing touches the main workspace folder until you decide it should. That clone is the sandbox. You can try things, throw things out, start over. Whatever happens in a session stays in the session until you save it back. This boundary covers the main workspace. A reference marked editable sits outside the clone, so changes to that reference are written directly and are not part of the workspace save.

​
Why sessions exist

Two reasons. To make agent work safe. Agents move fast. They write a lot. Without a sandbox, you’d be living with every change the agent made the moment it made it. That doesn’t work for shared folders, and it doesn’t really work for solo work either. To make shared workspaces work. If your team is in the same folder, you can’t have multiple people writing to it through agents at the same time. Sessions give each person their own clone to work in. Saving back is the moment of coordination.

​
Creating a session

Requires Palette Desktop v0.48.0 or later.
When you open a workspace, Palette Desktop opens it straight into a session. If the workspace has no session yet, Palette creates one for you, so you can start working right away. To start another session, click “New session”. The clone gets created on your machine. You’re in. New sessions get default names in order: “Session one”, “Session two”, and so on. You can rename a session by what you’re working on (e.g., “draft Acme outreach”). Sessions persist between launches, so you can leave one open and come back to it later. A workspace always has at least one session. If you delete the last one, Palette creates a new session in its place.

​
Working in a session

Inside a session, you run chats. One chat or several, your choice. Each chat is a conversation with an agent. The agent reads from and writes to the same sandboxed clone. You can also run multiple sessions in parallel:
  • Different sessions for different angles of the same work
  • Long-running work in one, quick tasks in another
  • Two teammates working on the same workspace at the same time, each in their own session

​
Updating a session

Requires Palette Desktop v0.48.0 or later.
Because a session is a clone, the main folder can move ahead while you have a session open. For example, a teammate saves their work back, or your synced folder changes on another device. Palette updates the session from the folder automatically. When the folder’s changes merge cleanly with your session, Palette pulls them into your clone without asking. You keep working on top of the current folder instead of an old copy. If the folder and your session changed the same file in ways that collide, Palette doesn’t merge on its own. Instead:
  • The session header shows Resolve conflict in place of Save
  • The inspector marks each file in conflict
  • The session’s row in the sidebar keeps a conflict mark until you resolve it
Click Resolve conflict to review the proposed merge for each file. Each file has a plain-language summary and a diff you can expand. You can accept the resolution, cancel, or hand the conflict to the agent in the chat to resolve.

​
Saving back

Requires Palette Desktop v0.48.0 or later.
When the session is ready, you save it back to the main folder. This is the only moment when work inside the cloned workspace touches the main workspace folder. Every session has a header at the top of the chat. It shows the session name, how many changes the session holds (for example, “3 changes”), and the action that moves them:
  • Save to workspace when the session has changes and nothing collides
  • Resolve conflict when the folder and the session changed the same file
To review your changes before saving, click the change count. The inspector opens on its Overview, which lists every file the session changed. Click Save to workspace to save. Palette writes all of the session’s changes to the main folder in one step, with no confirmation dialog. Palette checks for conflicts before you save, so a collision shows as Resolve conflict instead of a Save that fails. Resolve it first, then save.

​
Throwing a session away

If a session went nowhere, you can discard it. The clone is deleted and your main workspace folder is untouched. Changes already made to an editable reference are outside that rollback and remain in the referenced folder. This is part of what makes agent work feel safe. The cost of trying something is low.

​
Next