Your First Grove

A grove is Orchard's fundamental unit — a complete development workspace that combines a VM (the seedling) running one or more devcontainers (the fruits), all rooted in a git repository.

Orchard discovers the environment spec from your repository in this order:

devcontainer.json (preferred)
devfile.yaml / devfile.yml (fallback)
Default devcontainer seed (last resort)

You can override this with the --spec flag on grove plant. See Environment Specs for details.

Planting a Grove

The grove plant command takes a repository URL and provisions the full environment:

code

trowel grove plant https://github.com/your-org/your-repo

Available flags:

Flag	Short	Description	Default
`--branch`	`-b`	Branch to check out	`main`
`--name`	`-n`	Friendly name for the grove	(auto-generated)
`--machine`	`-m`	VM size: `small`, `medium`, `large`	`small`
`--spec`	`-s`	Environment spec: `auto`, `devcontainer`, `devfile`	`auto`

Examples:

code

# Specific branch with a custom name
trowel grove plant https://github.com/your-org/your-repo \
  --branch feature/my-feature \
  --name my-feature-workspace
 
# Larger machine size
trowel grove plant https://github.com/your-org/your-repo \
  --machine medium
 
# Force devfile spec (skip devcontainer.json)
trowel grove plant https://github.com/your-org/your-repo \
  --spec devfile

Grove Lifecycle

Groves progress through several states during provisioning:

State	Description
`PREPARING`	Initial setup
`PLANTING`	VM and container provisioning in progress
`GROWING`	Environment starting up
`FLOURISHING`	Ready — SSH access available
`DORMANT`	Suspended, preserving state
`CLEARING`	Teardown in progress
`CLEARED`	Deleted
`BLIGHTED`	Error state

Use trowel grove list to watch state progress. A grove is ready to connect when it reaches FLOURISHING.

Inspecting a Grove

code

# List all groves and their states
trowel grove list
 
# Show full details for a specific grove (VM info, containers, SSH connection string)
trowel grove show <grove-id>

Connecting to a Grove

Once a grove is FLOURISHING, connect via SSH:

code

trowel grove connect <grove-id>

This executes the SSH connection directly using the grove's generated connection string. You can also retrieve the raw SSH config block for use with VS Code Remote SSH:

code

GET /api/groves/<grove-id>/ssh-config

Clearing a Grove

When you no longer need a grove:

code

trowel grove clear <grove-id>

You will be prompted to confirm. Use --force to skip the prompt.

Suspending and Resuming

You can stop a grove to free resources while preserving its state, then start it again later:

code

# Stop a grove (transitions to DORMANT)
curl -X POST http://localhost:8080/api/groves/<grove-id>/actions/stop
 
# Start a grove again (re-provisions from DORMANT)
curl -X POST http://localhost:8080/api/groves/<grove-id>/actions/start

CLI subcommands for stop/start (trowel grove stop / trowel grove start) are coming soon. For now, use the API directly.

Installation

Command Reference