OOrchard

Getting Started

Orchard is a self-hosted cloud development environment platform. This guide walks you through setting up the Orchard server, installing the Trowel CLI, and planting your first grove.

Prerequisites

  • Docker & Docker Compose — used for PostgreSQL and devcontainer management
  • QEMU — used to provision isolated VMs for each grove

Install QEMU on Linux (Ubuntu/Debian):

code
apt install qemu-system-x86 qemu-utils

Install QEMU on macOS:

code
brew install qemu

macOS is supported via HVF acceleration (no KVM required). Prebuilt macOS binaries are not yet available — you must build the server and CLI from source on macOS. See below.

Install the Orchard Server

Download the latest server binary from the releases page:

code
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/orchard-server-linux-amd64.tar.gz
tar xzf orchard-server-linux-amd64.tar.gz
 
# Linux arm64
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/orchard-server-linux-arm64.tar.gz
tar xzf orchard-server-linux-arm64.tar.gz

Start PostgreSQL and the server:

Create a docker-compose.yml in your working directory:

code
services:
  postgres:
    image: postgres:16-alpine
    container_name: orchard-postgres
    environment:
      POSTGRES_USER: orchard
      POSTGRES_PASSWORD: orchard
      POSTGRES_DB: orchard
    ports:
      - "5432:5432"
    volumes:
      - orchard-postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U orchard"]
 
volumes:
  orchard-postgres-data:

Then start PostgreSQL and the server:

code
docker compose up -d postgres
./orchard-server

The API server starts on port 8080.

For local testing, you can skip PostgreSQL entirely by using the dev server: trowel dev-server start. It uses an embedded H2 database. See the CLI reference for details.

Option B: Build the server from source

Clone the repository and build the server:

code
git clone https://github.com/orchard-cde/orchard.git
cd orchard
docker compose up -d postgres
./gradlew :trellis:bootRun

Requires Java 25+ and Git.

Install the Trowel CLI

Download the Trowel CLI binary from the releases page:

code
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/trowel-linux-amd64.tar.gz
tar xzf trowel-linux-amd64.tar.gz
sudo mv trowel /usr/local/bin/
 
# Linux arm64
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/trowel-linux-arm64.tar.gz
tar xzf trowel-linux-arm64.tar.gz
sudo mv trowel /usr/local/bin/

Verify the download against the SHA-256 checksums published on the release page:

code
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/checksums-sha256.txt
sha256sum -c checksums-sha256.txt --ignore-missing

Verify the installation:

code
trowel --version

Option B: Build the CLI from source

Build the Trowel fat JAR from the repository:

code
git clone https://github.com/orchard-cde/orchard.git
cd orchard
./gradlew :trowel:fatJar

Add a shell alias for convenience:

code
alias trowel='java -jar /path/to/orchard/trowel/build/libs/trowel-0.3.0-all.jar'

Requires Java 25+ and Git.

Configure the CLI

Initialize your local configuration:

code
trowel config init

This creates ~/.orchard/config.toml with defaults pointing to http://localhost:7778 and generates a cultivator UUID to identify you to the server.

Verify the Connection

Check that the CLI can reach the server:

code
trowel status

Next Steps

Your First Grove