User guide
The manual, one chapter per topic, in the order you meet things in the UI: install, sessions, the panes, remote access, the command line and the settings. The feature pages show what each part looks like; the guide says how it works and what to set.
Get started
Install
What Sessionboxer needs (Docker, Node 22, a Claude, ChatGPT or Devin subscription) and the five ways to install it, from a one-line script to Docker Compose on a home server.
Connect your agent
First run: paste a token for Claude Code, Codex or Devin in Global settings, where it is stored, and the defaults every session inherits (git identity, CPU and memory).
Sessions
Start a session
Create a session from git URLs or a folder on your machine, pick the model and standing instructions, pull the agent's changes back to your folder, and stop, resume or delete the box.
Talk to the agent
How the chat works in Sessionboxer: folded tool calls, attached files and pasted screenshots, offline dictation with whisper.cpp, the Markdown prompt box and the message queue.
Snapshots and forks
Sessionboxer snapshots the whole container after each turn. Fork a new session from any snapshot, continue the conversation, start fresh or hand off to a different agent.
Revert and branches
Every turn divider has Revert to here: the chat goes back to that point in the same box and what followed is kept as a branch you can switch to later.
Videos, documents and diagrams
Ask the agent to record its screen, take a screenshot or export a PDF and the file plays or renders in the chat, with captions and optional narration. Markdown and Mermaid render too.
Watching the agent
Desktop
The Desktop pane shows the box's Linux screen next to the chat. Read-only while the agent works, yours to click and type in when it is idle or when you press Take control.
VS Code, terminals and themes
Open VS Code on the agent's files, as many shells as you want, file links from the chat straight into the editor, and eleven themes shared between the UI and VS Code.
Context window
The gauge above the prompt box, the per-turn token and cost figures, what a compaction dropped and kept, and the Context pane's breakdown by system prompt, tools and messages.
Usage limits
Three bars show your Claude or Codex usage windows. When a limit is hit the session keeps the refused prompt, counts down to the reset and can continue by itself.
Inspect LLM
Inspect LLM records each request and response between Claude Code and the Anthropic API: exact bodies, a parsed tree and a diff against the previous call. Also covers a company proxy.
Verification
After each turn the agent plans a few test cases, runs them in the box's browser and desktop, fixes what fails and answers with a captioned video. Per session or on demand.
Working with code
Pull requests
Attach a GitHub or Bitbucket Data Center PR to a session: comments and reviews in a table, failed checks with Fix buttons, notifications, and auto-merge when the checks pass.
Scheduled tasks
Run a prompt every night, every Monday or every hour: into an existing session or a fresh one from a template, with run history and catch-up for missed runs.
Docker inside sessions
Give a session its own Docker daemon, unprivileged with Sysbox or privileged without it, and pick the address block its networks use so they do not collide with yours.
Windows and macOS sessions
Pick QEMU · Windows or QEMU · macOS as a session's environment: how the base disk is installed once, what runs inside the VM (agent, repositories, MCP servers, terminal), what the host needs, and the limits.
The agent and Sessionboxer
The built-in sessionboxer MCP server: whoami and docs, actions on the agent's own session (PRs, snapshots, queue, panes, verification), cross-session tools, and the Off / This Session / All Sessions policy with approval cards.
USB devices
Connect a USB device on the machine to one session from its header menu, how the box follows re-enumeration, and where it works: Docker Engine on Linux, WSL2 with usbipd-win, not Docker Desktop.
MCP servers
Add command or HTTP MCP servers in Global settings, import a mcpServers JSON block, mark tokens as secret, and toggle servers per session without losing the conversation.
GitHub login
Connect GitHub through the GitHub CLI's login: the agent gets GitHub's MCP server, gh and git push work in the box, and several accounts can share one session.
Bitbucket Data Center
Paste an HTTP access token for your self-hosted Bitbucket and the box can clone, push and use bb, a gh-like CLI, for pull requests. Bitbucket Cloud is not covered.
Corporate proxy
Sessionboxer copies the CA certificates your machine trusts into every box, so agents and MCP servers behind a TLS-inspecting proxy do not fail on self-signed certificate errors.
Remote access
Access token and devices
Everything Sessionboxer serves is behind a login. How the access token, the pairing link and the device list work, and how to revoke a browser or rotate the token.
Tunnels
Pair another device over the local network or through an outbound tunnel: a Cloudflare quick tunnel, the Sessionboxer tunnel with a stable name, or your own server over SSH.
Your own address
Serve Sessionboxer on an address you control: a Tailscale or Headscale network, a named Cloudflare Tunnel with Access in front, or a VPS behind Caddy, with the environment variables each needs.
On the phone
Below 800 px the UI becomes a phone layout with tabs, a keyboard bar for the desktop and an installable app. Web Push tells you when a turn ends or a PR gets feedback.
Reference
Command line
sessionboxer serve, service install, new, ls, open, stop, resume and rm: start the server, run it in the background and open sessions from a terminal, locally or against a remote server.
Where things live
config.json, the SQLite database, session containers, the Sandbox and snapshot images, downloaded binaries and models, and the SESSIONBOXER_* environment variables.
Troubleshooting
Docker permission errors, a Sandbox image that will not pull, self-signed certificate errors behind a proxy, unreachable private addresses, and what differs on macOS.
MCP tools reference
The two MCP servers every session's agent gets: desktop (screenshot, zoom, mouse, keyboard, scroll, wait, recordings with captions and narration) and sessionboxer (whoami, docs, PRs, snapshots, queue, Auto QA, notifications, panes, other sessions, schedules), each tool with its parameters, limits and what it returns.
For contributors
Where the architecture and decision records live, how the npm workspaces are laid out, and how a release is cut and published.
Generated from docs/GUIDE.md in the Sessionboxer repository, which is also readable as one long page there.