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.
Prerequisites
Section titled “Prerequisites”- Host access to the machine.
- Edit access to the project.
- A project that belongs to the machine’s organization.
Attach a project
Section titled “Attach a project”- Open the machine menu.
- Select Machine settings.
- Under Projects, select Attach.
- Select a Project and an Environment.
- Select Attach to confirm.
orchard sandbox link add my-machine storefront --env stagingIf you omit --env, Greenhouse uses the project’s default environment. To list attached projects, run orchard sandbox link list my-machine.
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.
Use the variables
Section titled “Use the variables”Each attached project becomes a file:
~/.config/orchard/env/<project-slug>.envLogin shells, terminals, and scripts load every file in that directory:
echo $STRIPE_PUBLISHABLE_KEYpsql "$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.
File contents
Section titled “File contents”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, andANTHROPIC_BASE_URL.
If the environment defines its own DATABASE_URL, the file uses that value.
Who can read the values
Section titled “Who can read the values”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.
Detach a project
Section titled “Detach a project”- Open the machine menu.
- Select Machine settings.
- Under Projects, select the X next to the project.
orchard sandbox link remove my-machine storefrontOrchard removes the env file on the next sync.
Related resources
Section titled “Related resources”- Configure setup and run scripts - Use the attached variables in setup and run scripts.
- Share a machine - Review what guests can read on a machine, including env files.