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`	Stopped — VM and containers destroyed; restart with `grove start`
`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.

Through the SSH gateway

Production deployments (and trowel dev-server, which starts a gateway on port 2222) route SSH through the SSH gateway. Register a key once:

code

trowel ssh-key add

This generates ~/.orchard/keys/default and registers its public key with your account. Then connect using the grove ID as the SSH username:

code

ssh -i ~/.orchard/keys/default -p 2222 <grove-id>@<gateway-host>

Use localhost as the gateway host with trowel dev-server. See SSH Key Commands to register an existing key instead.

Directly (local/dev)

On a local setup you can also connect straight to the seedling:

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.

Stopping and Restarting

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

code

# Stop a grove (transitions to DORMANT)
trowel grove stop <grove-id>
 
# Start a grove again (re-provisions from DORMANT)
trowel grove start <grove-id>

Stopping a grove destroys its VM, including the VM's disk, and its containers. Only the grove record (repository, branch, machine size, and environment spec) is kept. grove start provisions a fresh VM and clones the branch again, so commit and push any work before stopping — anything not pushed to the remote is lost.

See the API Reference if you'd rather call the underlying endpoints directly.

Installation

Command Reference