Machines
A machine is the Linux environment that your sessions run on. It belongs to the person who created it, called the host, and to that person’s organization. This page explains what each runner provides, what survives a stop, and which limits apply, so that you know what to keep on the machine and what to push to GitHub.
Status
Section titled “Status”| Status | Meaning |
|---|---|
| Creating | The runner is provisioning the machine. |
| Starting | The machine is booting, or resuming after a stop. |
| Running | The machine is ready. Sessions, terminals, SSH, and previews work. |
| Stopping | The machine is shutting down. Orchard keeps its disk or snapshot. |
| Stopped | The machine is not running. |
| Deleting | Orchard is removing the machine and everything on it. |
| Error | The machine failed. The status message states why. |
A machine can also show Applying while Orchard carries out a change, or Apply failed if the change did not succeed.
Runners
Section titled “Runners”The runner is fixed when you create the machine.
Kubernetes
Section titled “Kubernetes”The machine is a pod on the instance’s cluster, managed by the agent-sandbox controller. On clusters with Kata Containers, each machine is a lightweight virtual machine with its own kernel.
- Disk: A persistent volume mounted at
/persist, 10 GiB by default. It holds your home directory, repositories, worktrees, agent history, and SSH host keys. A stop does not remove it. The rest of the root filesystem is not kept across a stop. - Network: Internet egress only. Inbound connections come only from the Orchard server.
- Previews: Private to people with access to the machine.
- Forking: Available when the cluster can snapshot the machine’s storage.
Vercel
Section titled “Vercel”The machine is a Vercel Sandbox on the operator’s Vercel account.
- Disk:
/persistis a Vercel drive that belongs to the machine, 50 GiB by default. Orchard deletes the drive only when you delete the machine. If Vercel loses the sandbox, the next start creates a new sandbox with the same drive. - Snapshots: Stopping the machine snapshots the rest of its filesystem. Orchard keeps the last three snapshots. They do not expire.
- Processes: Running processes do not survive a stop. Orchard restarts its own services on the next start. You restart your dev servers.
- Time limit: Vercel stops a sandbox after a timeout, 60 minutes by default. Orchard extends the timeout in 30-minute steps while the machine is in use. If Vercel stops the machine, it shows Stopped with the message
Stopped by provider timeout. - Network: Ports are reachable from the internet. The agent server and the SSH bridge require a per-machine secret. Preview ports are public.
- GitHub: Vercel’s egress proxy adds the host’s GitHub token to requests to
github.comandapi.github.com. The token is not stored in the machine. - Forking: Requires Vercel drive forks on the operator’s plan. Without them, the fork option is hidden for machines with a drive.
Image and tools
Section titled “Image and tools”A new machine starts from Orchard’s machine image on Kubernetes, and from Vercel’s universal image on Vercel, unless the operator selected another image.
Orchard’s image includes sshd, git, tmux, ripgrep, Node.js 22, Claude Code, opencode, fx, and Codex. On another image, Orchard installs what is missing on boot.
Your shell runs as the dev user. The dev user has passwordless sudo.
Repositories
Section titled “Repositories”Repositories live in the home directory as ~/<name>. The home directory is /persist/home.
To add a repository, select Add repository in the sidebar. The sheet has three modes: Clone, New, and Open folder. Only the host can use it. Guests can start a new empty repository from the home page.
To add a repository from the CLI, run the following command:
orchard sandbox repo add my-machine https://github.com/acme/apiClones use the host’s GitHub access and run in the background. The repository named at creation logs to ~/.clone.log.
Setup script
Section titled “Setup script”The setup script of a machine runs as dev on first boot. It logs to ~/.setup.log. It runs again on later boots until it succeeds once.
Use it for language runtimes, global tools, and dotfiles. To edit it, go to Settings > Machine. From the CLI, use orchard sandbox update --setup.
To run commands for each session of a repository, use .orchard/greenhouse.json instead.
Agent credentials
Section titled “Agent credentials”Your Claude token, OpenAI key, and AI Gateway key are stored on your account. Every machine you host uses them. When you change one, Orchard syncs it to those machines. Guests do not need their own credentials, because they run the host’s agent.
Some sign-ins stay on one machine instead of your account. These are the ChatGPT sign-in for Codex, and the fx sign-ins.
Actions by role
Section titled “Actions by role”| Action | Host | Guest | Read-only guest | Organization admin |
|---|---|---|---|---|
| Start | Yes | Yes | No | Yes |
| Stop | Yes | No | No | Yes |
| Delete | Yes | No | No | Yes |
| Fork | Yes | No | No | No |
For the full list of permissions, refer to What each role can do.
A stop ends running agents, terminals, and dev servers. Files on disk remain.
Deleting a machine removes everything on it, including unpushed branches. On Vercel, it also removes the drive and snapshots. You cannot recover them.
Forking
Section titled “Forking”Forking creates a new machine with a copy of the disk and the same sessions. The host of the source machine becomes the host of the copy.
Only the host can fork a machine, because the copy contains the host’s home directory and credentials. The fork counts against your machine limit.
| Runner | How the copy is made |
|---|---|
| Kubernetes | A volume snapshot of the home volume, restored into the volume of the new machine. A forked machine has 30 minutes to start, instead of 10. |
| Vercel | A fork of the last saved snapshot and a fork of the drive. Stop the machine first to include recent changes. |
To fork a machine, open the machine menu and select Fork machine. From the CLI, run the following command:
orchard sandbox fork my-machine --name my-machine-experimentThe default name is <name>-fork.
Limits
Section titled “Limits”The operator sets these limits. The following values are the defaults.
| Limit | Default | Behavior |
|---|---|---|
| Machines per person | 1 | Creating or forking past the limit fails. Superadmins can change the limit per person in Instance admin > Greenhouse, and have no limit themselves. |
| Idle stop | 60 minutes | Orchard stops a running machine with no terminal or SSH activity for this long. A working agent counts as activity. |
| Maximum lifetime | 168 hours | Orchard stops a machine this long after its last start, whether or not it is active. Orchard does not delete it. |
| People per machine | 50 | Fixed. |
| Active share links | 50 | Fixed, per machine. |
The audit log records each stop caused by a limit.
Related resources
Section titled “Related resources”- Get started - Create a machine and start your first session.
- Connect an editor over SSH - Work on a machine from a desktop editor or a terminal.
- Preview a session - Open a dev server that runs on the machine.