Skip to content
Install

Attach an Orchard project

An agent that runs your app needs the same configuration as your deployed app. Instead of copying variables by hand, attach a project to the machine. Orchard writes one of the project’s environments into the machine as an env file that shells load, and keeps the file up to date when the variables change.

  1. Open the machine menu.
  2. Select Machine settings.
  3. Under Projects, select Attach.
  4. Select a Project and an Environment.
  5. Select Attach to confirm.

A machine can have one environment per project. Attaching another environment of the same project replaces the first. The audit log records each attach and detach.

Each attached project becomes a file:

~/.config/orchard/env/<project-slug>.env

Login shells, terminals, and scripts load every file in that directory:

echo $STRIPE_PUBLISHABLE_KEY
psql "$DATABASE_URL"

The file is readable only by the dev user. Orchard rewrites it on each sync, so do not edit it.

When you change a variable on the environment, Orchard updates the file. Open shells keep the values they loaded. Open a new terminal to pick up changes.

The file contains:

  • Shared variables: The environment’s shared variables, as KEY='value' lines.
  • DATABASE_URL: The connection string of the environment’s first managed database, if public access is on for that database. The connection uses TLS and the public address. If public access is off, the file has a comment instead.

The file leaves out these values and adds a comment for each:

  • Secret variables: Orchard keeps secret values write-only. Set them on the machine yourself.
  • Variables that change how tools run: For example, PATH, HOME, LD_PRELOAD, GIT_*, NODE_OPTIONS, and ANTHROPIC_BASE_URL.

If the environment defines its own DATABASE_URL, the file uses that value.

The host and guests can read the file, because they can open terminals on the machine. Attach only variables that you are comfortable sharing with those people.

If the person who attached a project loses edit access to it, Orchard stops writing its variables to the machine.

  1. Open the machine menu.
  2. Select Machine settings.
  3. Under Projects, select the X next to the project.

Orchard removes the env file on the next sync.