Get started
In this guide, you create a Greenhouse machine, give it a credential for a coding agent, and start a first session on one of your repositories. When you finish, an agent works on its own branch on the machine, and you can review its changes in the workspace.
Prerequisites
Section titled “Prerequisites”- An Orchard instance with the
greenhousegraft installed. If Greenhouse is not in the dashboard sidebar, refer to Troubleshooting Greenhouse. - Membership in an organization. Organization guests cannot create machines.
- A GitHub account linked to Orchard, to clone private repositories and open pull requests. Link it in Account settings > Connections.
- The Orchard CLI, if you use the CLI steps.
1. Add an SSH key
Section titled “1. Add an SSH key”Orchard requires an SSH key to create a machine. Editors and ssh use the key to connect.
- Go to Account settings > Greenhouse.
- Under SSH identities, select Add identity. To use the keys on your GitHub profile, select Import from GitHub instead.
- Paste a public key.
Run the following command. It generates a key, registers it on your account, and configures ssh.
orchard sandbox ssh-config --install2. Add an agent credential
Section titled “2. Add an agent credential”The default agent uses your Claude token when you have one. Claude Code requires it.
Create a token on any computer with Claude Code installed:
claude setup-tokenStore the token in Orchard:
- Go to Account settings > Greenhouse.
- Under Agent credentials, paste the token into the Claude Code field.
- Select Save.
Run the following command, paste the token, and press CTRL + D.
orchard sandbox credentials set --claude -Orchard encrypts the token and does not show it again.
For other agents and sign-in methods, open a running machine and go to Settings > Agents.
3. Create a machine
Section titled “3. Create a machine”- In the dashboard sidebar, select Greenhouse.
- Select New machine.
- (Optional) Enter a Name. It must be a lowercase DNS label of up to 63 characters. Orchard generates a name if you leave it empty.
- If the instance offers more than one runner, select one under Runs on.
- If you have more than one SSH identity, select one under SSH key.
- Select Continue.
- Select a repository to clone on first boot. To add a repository later, select Skip.
- Select Continue.
- (Optional) Enter a Setup script. It runs once, on the first boot of the machine.
- Select Create machine.
The machine status changes from Creating to Starting to Running.
orchard sandbox create my-machine --repo https://github.com/acme/app --wait--wait returns when the machine is ready. --runner selects a runner. The instance default applies if you omit it.
The first boot on an image without the required tools takes a few minutes. Orchard installs the tools during that boot.
If Orchard reports Sandbox limit reached, ask a superadmin to raise your limit. The default limit is one machine.
4. Start a session
Section titled “4. Start a session”- Open the machine. When it is Running, the home page shows What should we build?.
- Below the prompt, select the repository for the session.
- Enter what the agent should do.
- (Optional) To have the agent propose a plan without editing files, change Build to Plan, read only.
- Select Start session, or press
ENTER.
orchard sandbox session create my-machine app --prompt "Fix the flaky login test"--base selects a base branch. The repository’s default branch applies if you omit it.
Greenhouse creates a git worktree on a new branch named orchard/<slug> and sends your prompt to the agent. The session appears in the sidebar under its repository, and its row shows what the agent is doing.
To run another agent at the same time, start another session. Each session has its own branch and worktree.
Next steps
Section titled “Next steps”- Review the agent’s work and leave comments on its diff
- Install dependencies in each new worktree
- Open a pull request from the session
Related resources
Section titled “Related resources”- Machines - Learn what each runner provides, what persists across a stop, and which limits apply.
- Connect an editor over SSH - Open a session in VS Code, Cursor, or Zed.
- Share a machine - Invite people from your organization to work on the machine with you.