Sandboxes and sessions
A sandbox is a container with your code and a coding agent in it, created for you to work in and thrown away when you are done. A session is one conversation with the agent inside it. This is the loop you will spend most of your time in.
Launching a sandbox
From a project, choose Launch and pick:
- The environment — where the container runs. Any environment in the same workspace.
- The agent definition — which agent, told what. Your organization starts with two, and the one matching your credential is already the default; see Agent definitions when you want your own.
The launch shows a timeline as it goes. A repository-backed project's first launch is the slow one, because its image is being built; later launches reuse it.
Launchability is computed per person: it asks whether you have a credential for the agent that definition names. A definition a teammate can launch and you cannot means you are missing a credential for that agent, not permission. → Why a definition can be unlaunchable for you
Working in a session
When the sandbox is ready you get a session: type what you want, and the agent reads, edits, runs commands and reports back. It has a real shell in a real container, so it can run your tests and see what happened.
The transcript is held server-side. You can close the tab, come back later, and continue — and you can read a finished session's transcript afterwards as a record of what was actually done.
What persists
| Survives | Notes | |
|---|---|---|
| Session transcript | Yes, beyond the container | The record outlives what produced it |
| Files in the container | Only while the container lives | Commit and push anything you want to keep |
| Work pushed to your repository | Yes | It is on GitHub, not here |
| The coding-agent credential in use | Frozen for the container's life | A credential change needs a fresh runtime — see below |
| Artifacts a session produced | Yes, attached to the session |
A sandbox is disposable by design. Anything the agent wrote that is not committed and pushed goes away with the container. If a session did something valuable, get it onto a branch before you stop the runtime.
Credentials do not update in place
A coding-agent credential is frozen into the container at launch. Rotating or replacing it does nothing to a container that is already running. To use a new credential, launch a new runtime.
Stopping and reclaiming
You can stop a sandbox when you are done; environments may also reclaim idle ones. Stopping is not destructive to your history — the sessions and their transcripts remain.
When a launch does not finish
→ A launch that will not finish — each step, and the usual cause of a stall there.