Start a session: repositories, model, instructions, stop and resume

Start a session

Click + New (or just type into the first screen): a prompt box, and under it, left to right, the Environment (Docker · Linux by default, QEMU · Windows or QEMU · macOS — logo only when closed; one the host cannot run yet says not installed and picking it opens a dialog with what it needs and where to install it), the Agent (its logo; one without a login shows not connected and picking it opens Connect a Provider), the Model, the repositories, Advanced… and Start. Environment and Agent are remembered for the next New session. Everything else is behind Advanced…, a dialog with the sections on the left and their controls on the right — Environment (the Linux/Windows/macOS pick, Docker inside the Sandbox, CPU and memory limits, snapshots), Agent (fast mode, effort, the system prompt), MCP & connectors (the built-in desktop and sessionboxer servers, always on, with the sessionboxer policy under it; the Git connectors and the git author; your own MCP servers), Auto QA (verify each turn end to end) and, for Claude Code, Debug (Inspect LLM). Each caption has a ? that opens its explanation; the defaults come from Global settings. Type what the agent should do (Cmd/Ctrl+Enter starts), or start with no prompt and talk to it in the Session. List the repositories the session works on: none (the Workspace starts empty), one, or several (a frontend, a backend, the CI repositories, the docs…) with + Git repository / + Host folder. Each lands in its own directory in the box, /workspace/<name>, <name> being the repository or folder basename (-2, -3 on a clash; change it in the name field). The Workspace root /workspace stays the agent's working directory and the place for anything that belongs to no repository (recordings, notes); /workspace/.sessionboxer/repos.json lists the repositories, and the agent's briefing tells it to treat each top-level directory as its own git repository and to say which one a path, commit or PR belongs to.

• Clone a git URL: any URL git clone accepts, optionally a branch or tag. With a GitHub entry enabled for the new session (see GitHub with one click), private GitHub repositories clone as that account, and git@github.com:… SSH URLs are cloned over HTTPS the same way (the box has no SSH keys). Likewise a Bitbucket entry clones private repositories of that host (https://bitbucket.example.com/scm/KEY/repo.git, the …/projects/KEY/repos/repo/browse page URL or ssh://git@bitbucket.example.com:7999/KEY/repo.git, all over HTTPS). Other private hosts need credentials embedded in the URL for now. Below the URL, Git author for commits made in the Sandbox shows the name and email the agent's commits will carry (user.name / user.email in the box, author and committer): prefilled from Global settings (or, when blank there, from your machine's own git config), editable for this session only, with Reset to the global identity to go back; it is fixed once the session exists and travels with forks. The header's source tooltip shows what a session got.
• Copy a host directory: a folder on your machine (type the path or pick it with Browse…). Git repositories are copied the way git sees them (tracked and untracked files, but nothing ignored by .gitignore, so node_modules or build output stay behind), plus the .git folder so the agent can commit. Other folders are copied whole. Changes the agent makes stay in the box until you Pull to folder… (below).

The header shows one chip per repository (⋯ while it is being cloned or copied, ⚠ when that failed, ● when it holds uncommitted or unpushed work; hover for the branch and state). Click the chips to add a repository to a running session (cloned or copied in place, the agent is told on its next prompt) or remove one: the directory is deleted in the box, never your folder or the remote. Removing refuses when the repository has uncommitted changes, commits no remote has, or (for a copied folder) changes not yet pulled to your machine, until you confirm you want to lose them. Sessions created before repositories existed keep their single project at /workspace itself and cannot take a second one; start a new session for that.

Model lists the models the chosen agent offers (Claude Code: Sonnet/Opus/Haiku/Fable and its default; Codex: the GPT models your plan has; Cursor: the models your plan has, as its CLI lists them; Devin: the catalog your account has, grouped by family); leave it on Provider default to let the agent decide. The list is what the agent reported the last time a session of that provider started, so it is empty until you have run one. Next to it come the agent's other settings, when it has any: for Claude Code, Effort (default, low … max) and Fast mode; for Codex, Reasoning effort, Collaboration mode (default or plan first) and the rest of its options. Devin's Cloud tiers (Lite, Normal, Ultra) are not something its CLI offers; pick a model with the effort level you want instead (…-high, …-fast, …).

Claude Code only lets Sessionboxer pick from the aliases in Global settings → Agent → Claude model aliases (opus, sonnet, haiku, fable by default; that list is written to Claude's availableModels). Add an alias there if your account has a model the picker does not show; it takes effect for new sessions and for idle sessions right away.

System prompt (Advanced… → Agent; "Instructions for the agent" in Global settings → Agent) is prefilled from the global text and is fixed for the session once created (empty means none). These are standing rules given to the agent itself rather than left in a file it may or may not read: Claude Code gets them appended to its system prompt (on every start of the session, including Resume and rewinds), and Codex, Cursor and Devin, whose CLIs have no such hook, get them prepended to the first message of each conversation the box starts for the session (once; later messages go verbatim). They come on top of the Sandbox briefing and the project's own CLAUDE.md / AGENTS.md. The shipped default asks the agent to keep its name out of git (no Co-Authored-By trailer or "generated with" line: Claude Code's own byline is also switched off in the box); testing a change is not part of it, that is what Verify each turn end to end does. Session settings in a session's header ⋯ menu shows what that session got, in the same Environment / Agent / MCP & connectors / Auto QA / Debug layout as Advanced…; what can still change (model and options, MCP servers, snapshots, Auto QA, Inspect LLM) saves as you change it, the rest is read-only.

Optionally type the first prompt right there; it is sent as soon as the box is ready. The session title defaults to the first prompt and can be edited later.

Pull the box's changes into your folder

Sessions with a copied host folder (folder icon next to the agent logo in the list; a git mark means a clone) have Pull to folder… in the header; with several copied folders, pick which one at the top of the dialog. It compares that repository's directory in the box with the folder on your machine and shows what would change before anything is written: new files (+), changed files (~), files the agent deleted (−). Pull changes applies them; files ignored by git (node_modules, build output) and .git itself stay in the box, and anything you added or changed only on your machine is left alone. A file that changed on both sides is a conflict: it is skipped and marked kept yours, unless you tick Also overwrite… (you are asked to confirm). Symlinks that would point outside your folder are never written. Pull as often as you like; each pull records the new common state, so the next one only shows what changed since. Pulling waits for the agent's turn to end and needs the box running.

Stop, resume, delete

• Stop pauses the box. It uses no CPU or memory while stopped; the conversation, files, installed packages and everything else in the container are kept.
• Resume brings it back where it was. The agent reloads the conversation, so you can continue as if nothing happened.
• Delete removes the session, its container and its snapshots for good (forks started from it keep working).