Orchard

Cloud Development Environments - Growing the Future of Code

Orchard is a cloud development environment (CDE) platform that provisions ready-to-code workspaces from any Git repository. Think Gitpod, but with an orchard theme.

• devcontainer Support: Full compatibility with the .devcontainer specification
• VM-based Isolation: Each workspace runs in its own QEMU VM with Docker
• VS Code Remote SSH: Connect directly from your local VS Code
• Web UI (Canopy): Manage workspaces from your browser — separate repo
• CLI (Trowel): Plant and manage groves from the command line
• AI Coding Assistants: Attach AI-powered Bees (OpenCode, Claude Code, Gemini, Codex) to any grove

• Java 25+
• Docker & Docker Compose
• QEMU (for local VM provisioning)

# Clone the repository
git clone https://github.com/orchard-cde/orchard.git
cd orchard

# Start PostgreSQL
docker compose up -d postgres

# Build the project
./gradlew build -x test

# Start the dev server — runs orchard core (:7778) + the Canopy UI BFF (:7777)
trowel dev-server start        # open http://localhost:7777
trowel dev-server start --no-ui  # core only on :7778 (API only, no UI)

trowel dev-server start launches two processes:

• orchard-server (core, API only) on port 7778
• orchard-ui-backend (Canopy UI BFF) on port 7777 — serves the Canopy UI and reverse-proxies /api/** to core. Open http://localhost:7777 in your browser.

In dev mode, the UI auto-authenticates as the cultivator configured in your trowel config (~/.orchard/config.toml), so no localStorage setup is needed.

The BFF binary (orchard-ui-backend) is downloaded automatically from orchard-ui GitHub releases (linux-amd64, linux-arm64, macos-arm64) and cached at ~/.orchard/bin/orchard-ui-backend, sha256-verified against the release checksums. Pass --ui-version to pin a specific orchard-ui release. For an unpublished platform, or when working on orchard-ui itself, build it locally from the sibling orchard-ui/ checkout:

# In the sibling orchard-ui/ repository
./gradlew :backend:nativeCompile
cp backend/build/native/nativeCompile/orchard-ui-backend ~/.orchard/bin/

Fast UI-development loop — when actively working on orchard-ui source, run the Next.js dev server for hot-reload instead:

# In the sibling orchard-ui/ repository
npm run dev   # Next.js on :3000, talks to the core API at http://localhost:7778

# Build the CLI
./gradlew :trowel:fatJar

# Initialize configuration
java -jar trowel/build/libs/trowel-0.1.0-SNAPSHOT-all.jar config init

# Check server status
java -jar trowel/build/libs/trowel-0.1.0-SNAPSHOT-all.jar status

# Plant a grove (workspace)
java -jar trowel/build/libs/trowel-0.1.0-SNAPSHOT-all.jar grove plant https://github.com/user/repo

# List your groves
java -jar trowel/build/libs/trowel-0.1.0-SNAPSHOT-all.jar grove list

# Connect via SSH
java -jar trowel/build/libs/trowel-0.1.0-SNAPSHOT-all.jar grove connect <grove-id>

Pre-built native binaries are available for each release:

Each tarball contains a single statically-linked executable. Download, extract, and run:

# Example: download and run trowel on Linux amd64
curl -L https://github.com/orchard-cde/orchard/releases/latest/download/trowel-linux-amd64.tar.gz | tar xz
./trowel --version

On macOS, you may need to remove the quarantine attribute before running:

xattr -d com.apple.quarantine orchard-server
xattr -d com.apple.quarantine trowel

Each release includes a checksums-sha256.txt file. Verify a download with:

sha256sum --check checksums-sha256.txt --ignore-missing

┌─────────────────────────────────────────────────────────────┐
│                 Canopy (UI) — separate repo                 │
│        Next.js / React / MUI (orchard-cde/orchard-ui)       │
├─────────────────────────────────────────────────────────────┤
│                         Trowel (CLI)                        │
│                       Picocli Commands                      │
├─────────────────────────────────────────────────────────────┤
│                      Trellis (REST API)                     │
│              Spring Boot Controllers & Services             │
├───────────────┬────────────────────────┬────────────────────┤
│    Harvest    │        Nursery         │       Apiary       │
│  Devcontainer │    VM Provisioning     │   BeeKeeper (AI)   │
│    Parsing    │    (QEMU, AWS, GCP,    │ OpenCode, Claude,  │
│               │         Azure)         │   Gemini, Codex    │
├───────────────┴────────────────────────┴────────────────────┤
│                    Vine (Substrate Exec)                    │
│            CommandRunner / SshVine / SshExecutor            │
├─────────────────────────────────────────────────────────────┤
│                     Roots (Persistence)                     │
│               JPA Entities, Spring Data Repos               │
├─────────────────────────────────────────────────────────────┤
│                     Core (Domain Models)                    │
│        Grove, Seedling, Fruit, Seed, Bee, Cultivator        │
└─────────────────────────────────────────────────────────────┘

We use orchard/gardening terminology throughout the codebase:

orchard/
├── core/       # Domain models (Java records)
├── vine/       # Substrate-agnostic exec abstraction (Vine, CommandRunner, SshVine)
├── roots/      # Persistence layer (JPA, Flyway)
├── harvest/    # Devcontainer spec parsing
├── nursery/    # VM lifecycle management (QEMU, AWS, GCP, Azure)
├── greenhouse/ # Prebuild service (image caching)
├── apiary/     # AI assistant integration (BeeKeeper extension point)
├── fence/      # Authentication subsystem (OAuth2/OIDC device flow)
├── gateway/    # SSH gateway (MINA SSHD jumphost relaying to seedlings)
├── trellis/    # Spring Boot application (REST API + services)
└── trowel/     # Command-line interface

integration-tests/ (end-to-end tests spanning trellis, trowel, fence, nursery) is omitted above as a build-only module, not part of the shipped architecture.

For detailed documentation including architecture deep-dives and usage guides, see docs/TOC.md.

• Java 25 - Modern Java with records, virtual threads, pattern matching
• Spring Boot 4.1 - Application framework
• PostgreSQL - Database with Flyway migrations
• Picocli - CLI framework
• QEMU/KVM - Local VM provisioning
• AWS EC2 - Cloud VM provisioning (GCP Compute, Azure VMs planned)
• Gradle - Build system with Kotlin DSL

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/orchard
    username: orchard
    password: orchard

orchard:
  nursery:
    provider: qemu  # qemu, aws, gcp, azure
  qemu:
    base-image-path: /tmp/orchard/images/base.qcow2
    vm-storage-path: ${user.home}/.orchard/data/vms
    # enable-kvm/serial-output default per-platform (KVM on Linux, HVF on macOS)

active = "local"

[targets.local]
server = "http://localhost:7778"
cultivator = "<your-uuid>"

• OAuth2/OIDC authentication
• AWS EC2 cloud provider
• GCP Compute and Azure VM providers
• Workspace prebuilds and image caching
• Real-time status updates (Server-Sent Events)
• VS Code extension for direct integration — orchard-vscode-extension
• Multi-container workspace support
• AI coding assistant integration (BeeKeeper adapters — OpenCode, Claude Code, Gemini, Codex)

Orchard is licensed under the Apache License, Version 2.0. See the NOTICE file for attribution.

Contributions welcome! Please read the contribution guidelines before submitting PRs.