What a session is
A session is one isolated sandbox for one task: its own container, branch and environment on an organization server. Save merges back, finish discards.
A session in Isolation is one isolated sandbox for one unit of work. When you launch a session of a workspace, an organization server creates a container, clones the workspace's repos into it, loads the environment you chose, checks out a branch that belongs to that session alone, and starts your agents inside it. Five features in flight are five sessions, each with its own container, its own branch, its own data, and its own line in the cost view.
What a session owns
A session is not a shell on a shared box. Each one gets:
- Its own container. The runtime is OpenSandbox. The sandbox has its own filesystem, its own processes and its own ports. What one session installs, breaks or leaves running does not touch another.
- Its own branch. The workspace's file tree is a git repository, stored as an encrypted bundle in Isolation Cloud. At launch the server restores that bundle into
/workspaceand checks outsession/<id>offmain. Everything the session writes lands on that branch. - Its own environment. The variables and secret files of the environment you launched with are sealed in transit and materialized inside the sandbox for its lifetime, mode 0600, never in argv, URLs, bundles or git. See environments, variables and secret files.
- Its own agents. Every agent on the workspace rides in. An agent view is one conversation with one agent, a real harness session running inside the sandbox.
- Its own doors. Views through the doorman, an ssh route, a WebDAV address, a public preview link. Each points at this sandbox and no other.
The session is the launcher's. Only you can open it. An Owner or Admin of the organization can list it and stop it, which is the right that lets whoever pays for a Cloud Server stop a forgotten session, but they cannot open it.
The lifecycle
| Step | What happens | How you do it |
|---|---|---|
| Launch | the container is created, repos cloned, environment loaded, session/<id> checked out, agents started | Launch on the workspace, /launch <workspace> in a chat, session_launch over MCP or the CLI |
| Work | terminals, the code view, agents, ssh, previews | the session screen, or any door into it |
| Save | the session branch is committed and merged into the workspace's main; the bundle is written back | Save, /save, session_save |
| Pause and resume | the sandbox is frozen and brought back later | /pause, /resume |
| Finish | the container is destroyed; anything not saved is gone | Stop, /stop, session_stop |
From a chat the whole cycle is three lines:
/launch web in staging on The Mac as "login fix"
/save
/stopSave is safe to repeat. The server commits the session branch, merges it --no-ff into main, bundles the repository and writes it back with a compare-and-swap on the bundle's ETag. If another session of the same workspace saved first, the write is refused, the server pulls the new main, merges again and retries. A real conflict is reported rather than guessed: the session branch stays untouched and you resolve it from the sync dialog.
Finish is deliberate. session_stop says it plainly: the sandbox is destroyed and its work stops. A chat agent asked to stop a session asks you first unless you told it to.
How does a session get its own branch?
The workspace tree never lives on a server. It is a bundle in Isolation Cloud, encrypted end to end with a key derived per workspace. Launch pulls the bundle into the fresh sandbox, reconstitutes its git history into /workspace, and branches session/<id> off main. Two sessions of one workspace are two branches of one repository, so they merge like any two branches. Wipe any server's disk and nothing is lost: the next launch restores the same bundle on any server of the organization. The details are in nothing lives in the sandbox.
Why git worktrees on one laptop are not this
Worktrees give you separate directories with one checkout each, which solves exactly one problem: two branches open at the same time. Everything else is still shared. One node_modules, one set of environment variables, one port 3000, one database, one Docker daemon, one agent's rm -rf reaching every other tree. An agent running tests in one worktree competes for CPU with an agent in another, and when the laptop lid closes, every one of them stops. Nothing is attributable either: the laptop does not say which feature cost what.
A session is a different object. It is a container on an organization server, a Connected Server you own or a Cloud Server, so it keeps running with your laptop closed and opens from any browser. It measures its own CPU, memory, storage, egress and tokens. Its ports are its own, so three sessions can each serve on 3000. Its branch is a real branch of a real repository. When it is finished it is gone, and the next session starts from a clean image with the current main. The workspace persists; the session is disposable by design. That is what makes it safe to give one to an agent.
Questions
Can a teammate open my session?
No. A session belongs to the member who launched it. An Owner or Admin can list it and stop it, never open it.
What happens to my files when I finish a session?
The container is destroyed. Everything you saved is on the workspace's main branch in Isolation Cloud; anything you did not save is gone.
Is a session the same as a git worktree?
No. A worktree is a second checkout on the same machine, sharing its ports, processes, environment and CPU. A session is its own container with its own branch, ports, environment and cost line.