Host commands
orchardctl operates an Orchard instance from the machine that runs it. Use it to upgrade the instance, change settings that the dashboard cannot edit, and sign in when nothing else works. The installer adds it to the host, so it exists only on an installer host, not on a Helm install. The orchard CLI is a different tool, which deploys apps to any instance over its API.
| Command | Purpose |
|---|---|
orchardctl update |
Upgrade to the latest chart and images. |
orchardctl harden |
Close the registry to outside traffic and open the firewall for k3s. |
orchardctl config |
Read and change chart values. |
orchardctl env |
Read and change control-plane environment variables. |
orchardctl registry |
Set where builds can push. |
orchardctl policies |
Set which namespaces can reach tenant apps. |
orchardctl mcp |
Manage the MCP endpoint. |
orchardctl graft |
Install and manage grafts. |
orchardctl public-ip |
Set the default address for public ports. |
orchardctl hostname |
Change the dashboard domain, and add names that the dashboard answers on. |
orchardctl apps-domain |
Change the domain that app addresses end in. |
orchardctl letsencrypt-email |
Change where Let’s Encrypt sends notices. |
orchardctl claim |
Print a link that claims the instance. |
orchardctl login |
Print a one-time sign-in link. |
orchardctl password |
Set a password on the superadmin account. |
orchardctl backups s3 |
Show or change the S3 storage for backups and uploads. |
orchardctl stop |
Stop the instance. |
orchardctl start |
Start the instance. |
orchardctl restart |
Stop and start the instance. |
orchardctl logs [service] |
Follow logs for server, frontend, or mcp. |
orchardctl status |
Show the control-plane pods. |
orchardctl k3s |
Show the k3s version, apply a patch, or move to a newer minor version. |
orchardctl images |
Show the bundled images, and what each can move to. |
orchardctl image-gc |
Show or change when the node removes unused images, or remove them now. |
orchardctl sync |
Refresh these commands from the deployed image. |
orchardctl uninstall |
Remove Orchard, k3s, and everything on them. |
orchardctl licenses |
Print third-party notices. |
Most commands also exist with a hyphen, such as orchard-config and orchard-update. All commands except logs, status, and licenses need root.
Every command has help. Add --help to a command to read it.
The commands read paths from /etc/orchard/env. orchardctl is one binary that ships in the server image, with a build for each architecture. The hyphenated names are links to it.
update
Section titled “update”sudo orchardctl updateRuns the following steps in order:
- Runs
orchardctl harden, and writes Orchard’s image cleanup settings if the server has none. - On kernels that need them, sets the kernel setting for rootless builds and the AppArmor profile that lets container processes signal each other.
- Turns on, once, what newer releases run by default, and repairs log and metrics volumes that never bound.
- Picks newer versions of the images the chart runs.
- Runs
helm upgrade --installwith your values file, and waits for each deployment to roll out. If a new image does not come up, it goes back to the previous version. - Updates zot and cloudflared, and checks that Traefik writes the JSON access log.
- Refreshes the host commands.
- Applies the latest k3s patch.
- Upgrades Traefik, CloudNativePG, and cert-manager within their major versions, from their own charts.
Steps 4, 6, and 9 follow the third-party update policy: a release waits 7 days before it installs, and a release that fixes a known vulnerability in the running version installs at once. To turn off the image and add-on updates in steps 4, 6, and 9, add ORCHARD_ADDON_UPDATES=off to /etc/orchard/env. To turn off step 8, add ORCHARD_K3S_UPDATES=off.
The command restarts a deployment if its image has no tag or the tag latest, because Helm sees an identical pod template and the old image keeps running. A deployment on a release version rolls out when the new chart changes that version.
Any extra arguments go to helm upgrade.
New defaults on an existing host
Section titled “New defaults on an existing host”On its next update, a host installed earlier gets the same defaults as a new install. Orchard prints each change and edits the values file before the upgrade. To review the result, run orchardctl config list.
| Item | Change |
|---|---|
| Metrics | Sets metrics.enabled: true, including when an older installer wrote false. |
| Image scanning | Sets trivy.enabled: true. |
| Storage classes | Gives the log store, metrics, and scanner volumes the class that Postgres uses. |
| Log disk limit | Sets logs.maxDiskSpaceUsage from free disk. |
| Small machines | Under 8 GB of memory, reduces requests and limits for metrics, logs, and the scanner, keeps 7 days of logs, and runs one scan at a time. |
| Image tags | Removes server.image.tag and frontend.image.tag when they are latest, so the server and frontend run the versions of the installed chart. |
| Pull policy | Removes image.pullPolicy when it is Always and no Orchard image uses latest, so pods start from the image on the node. |
| Gateway API | Removes gateway.enabled when it is true. Orchard does not route apps through Gateway API, so the chart’s Gateway objects carry no traffic. |
| Backups | Sets objectStorage.local.enabled: true and r2Proxy.enabled: true, sized from free disk. |
| Database operator | Sets CNPG_OPERATOR_NAMESPACE to cnpg-system, if it is not set. |
| Image cleanup | Writes Orchard’s image garbage collection settings if the file does not exist, and restarts k3s once. |
| Install mode | Sets INSTALL_INGRESS_MODE from your values, if it is not set. The dashboard uses it to show these commands instead of Helm values. |
| Registry egress | Adds a builders.registryEgress entry for the bundled zot registry, if there is none, so that builds can push to it. |
Orchard turns on the local backup store only when no object storage is configured. It checks for R2_ENDPOINT, R2_ACCOUNT_ID, or R2_BACKUP_BUCKET in server.env, server.envFrom, r2Proxy.upstream.endpoint, and values at Instance admin > Configuration > Object storage. If it cannot read the database, it leaves the store off and prints the commands that turn it on.
Except for metrics.enabled and r2Proxy.enabled, which older installers wrote as false, and the latest image tags, Always pull policy, and gateway.enabled: true that they wrote, Orchard only fills in keys that are missing. It does not change a value you set.
These changes happen once. The top-level hostDefaults key records which defaults a values file has. If you turn something off afterward, it stays off:
sudo orchardctl config set trivy.enabled false --applyVolumes and Traefik
Section titled “Volumes and Traefik”A StatefulSet cannot change its StorageClass in place. For the log store and VictoriaMetrics, update checks the live volume. If it is bound, the values file is pinned to its class. If it never bound, update deletes the StatefulSet and its empty claim and recreates them on the class in the values file.
If the traefik release is missing any access log setting, update upgrades that release with --reuse-values on the deployed chart version. If that fails, it prints the helm upgrade command to run. For the settings it checks, refer to Traefik access logs.
harden
Section titled “harden”sudo orchardctl hardenMoves the image registry onto loopback, adds a password to it, and gives that password to the containerd mirror and the builders. It also opens an active ufw or firewalld for k3s, closes ports 9100/tcp and 8472/udp in that firewall to everything outside the pod and service networks, and makes the k3s kubeconfig readable only by root. It also renews the Barman Cloud plugin certificates when one is missing, cannot be read, or expires within 90 days, and then restarts the plugin.
update runs this command first. Run it directly only on a host that you do not want to upgrade yet. You can run it more than once.
ORCHARD_REGISTRY_PORT sets the loopback port. The default is 5000.
config
Section titled “config”sudo orchardctl config get signupModesudo orchardctl config set signupMode opensudo orchardctl config set server.replicas 3 --applysudo orchardctl config unset metrics.enabledsudo orchardctl config listsudo orchardctl config editReads and writes the chart values at /etc/orchard/values.yaml. Paths are dotted. Values are parsed as YAML, so true and 3 keep their types.
Changes are not deployed until you add --apply or run update. These values stay when you re-run the installer.
config set and config unset refuse to change a list. server.env is a list that holds JWT_SECRET and SECRETS_ENCRYPTION_KEY. Use orchardctl env for environment variables, and config edit for other lists.
| Path | Purpose |
|---|---|
signupMode |
open, invite_only, or closed. |
tenant.certClusterIssuer |
The ClusterIssuer for app certificates. |
ingress.tls.issuerRef.name |
The ClusterIssuer for the Orchard dashboard. |
server.replicas |
The number of API pods. |
cilium.enabled |
Cilium-backed policy and basic auth. |
metrics.enabled |
The built-in metrics stack. |
metrics.victoriametrics.retention |
How long metrics are kept, such as 7d. |
logs.enabled |
The log store. |
logs.retention |
How long logs are kept, such as 14d. |
logs.maxDiskSpaceUsage |
The disk limit for logs, such as 8GiB. |
logs.victorialogs.storage.storageClass |
The StorageClass for the log store. |
trivy.enabled |
The Orchard image scanner. |
trivy.maxConcurrentScans |
Scans running at once. |
objectStorage.local.enabled |
The S3-compatible store on this machine for backups and uploads. |
objectStorage.local.storage.size |
The volume size of that store, such as 40Gi. |
r2Proxy.enabled |
The backup proxy that databases use. |
r2Proxy.upstream.endpoint |
An S3 endpoint for backups, set in the values file. To set it in Orchard instead, use backups s3. |
updates.url |
The What’s new feed, or off. |
sudo orchardctl env listsudo orchardctl env get FRONTEND_URLsudo orchardctl env set SMTP_HOST smtp.example.comsudo orchardctl env set R2_BACKUP_BUCKET my-backups --applysudo orchardctl env unset UPDATES_URLsudo orchardctl env set PUBLIC_INGRESS_CNAME ingress.example.com --for frontendReads and changes the control plane’s environment variables. These are server.env entries in the values file. Each command changes one entry and leaves the others.
| Subcommand or flag | Result |
|---|---|
list |
Prints the names that are set, not the values. |
get |
Prints one value. |
set |
Adds the variable, or changes it in place. |
unset |
Removes the variable. |
--for |
With frontend or mcp, edits frontend.env or mcp.env. |
Changes are not deployed until you add --apply or run update. A variable set here locks the matching field in Instance admin. These settings stay when you re-run the installer.
registry
Section titled “registry”sudo orchardctl registrysudo orchardctl registry zot --applysudo orchardctl registry allow my-registry --label app=registry --port 5000sudo orchardctl registry remove my-registrySets the registries that builds can reach. A build to an unlisted registry fails at the push. allow replaces any entry for the same namespace. To build to a registry other than zot, refer to Use your own registry.
policies
Section titled “policies”sudo orchardctl policiessudo orchardctl policies set traefik,orchard --applysudo orchardctl policies reapplySets the namespaces that can reach tenant apps. reapply restarts the server, which rewrites the policy in every managed namespace.
sudo orchardctl mcpsudo orchardctl mcp enable --applysudo orchardctl mcp enable mcp.example.com --applysudo orchardctl mcp disable --applyTurns the MCP endpoint on or off and sets its hostname. A new install has one at the hostname you gave the installer, unless you turned it off.
enable with a new hostname moves the endpoint, and agents must reconnect at the new URL. The URL keeps the port that the instance serves on. enable with no hostname uses the one in values. Otherwise, it uses mcp.<app domain>, which the wildcard record for your apps covers. For any other hostname, create an A record first.
enable also copies JWT_SECRET from the server and creates MCP_SERVICE_TOKEN if there is none. Without both, every tool call fails at authentication. It also sets the issuerRef so that cert-manager issues a certificate. Without a certificate, Traefik serves its self-signed default and MCP clients refuse to connect.
disable removes the deployment at the next upgrade. To stop the server from answering without a redeploy, use the toggle at Instance admin > Configuration > Model Context Protocol.
sudo orchardctl graft searchsudo orchardctl graft add greenhouse --applysudo orchardctl graft listsudo orchardctl graft remove greenhouse --purgeInstalls and manages grafts, the Orchard extensions. For every subcommand, refer to Install grafts, or run orchardctl graft --help.
public-ip
Section titled “public-ip”sudo orchardctl public-ipsudo orchardctl public-ip set 203.0.113.10 --applysudo orchardctl public-ip unset --applyPins the default address for raw TCP and UDP ports and public databases. An organization that sets its own address overrides it. Setting it here locks the field at Instance admin > Configuration > Public exposure. To keep the field editable, set the address there instead.
hostname
Section titled “hostname”sudo orchardctl hostnamesudo orchardctl hostname add mango --applysudo orchardctl hostname remove mango --applysudo orchardctl hostname set orchard.example.com --applyLists, adds, and removes names that the dashboard answers on. Traefik routes by Host header, so a name that is not listed returns a 404 status. Use this for a Tailscale name, an mDNS name, a DNS record added later, or a renamed machine. A lan install starts with the addresses, hostname, .local name, and sslip.io name that the machine had during installation.
The list reads the values file. A name shows in the list as soon as you add it, and returns a 404 status until helm upgrade runs.
These names are matched, not certified. On an instance that terminates TLS, a name with no certificate causes a browser warning.
The primary hostname is not in this list. To change it, use set. The command changes ingress.host, which is the name that Traefik matches, and FRONTEND_URL, which is the name in generated links. It keeps the scheme and port that the instance serves on, and it prints what the change affects. Outside lan mode, the name must be a domain, such as orchard.example.com. Before you change it, read Dashboard domain, because everyone must sign in again.
To see what Traefik matches, run the following command:
sudo kubectl -n orchard get ingressroute orchard \ -o jsonpath='{.spec.routes[*].match}'apps-domain
Section titled “apps-domain”sudo orchardctl apps-domainsudo orchardctl apps-domain set apps.example.com --applyShows or changes the domain that app addresses end in. The command changes gateway.http.appDomain and APP_DOMAIN together, and removes a pinned PUBLIC_APP_DOMAIN from frontend.env. If tenant.wildcardDomains or PLATFORM_WILDCARD_DOMAINS is set, the command warns you, because these take precedence. Only new apps use the new domain. For details, refer to Apps domain.
letsencrypt-email
Section titled “letsencrypt-email”sudo orchardctl letsencrypt-emailsudo orchardctl letsencrypt-email unsetShows, changes, or removes the address where Let’s Encrypt sends notices. The address is on the letsencrypt ClusterIssuer, so a change takes effect right away and does not need --apply. Certificates are not affected. In lan and tunnel modes, the command stops, because these modes do not use Let’s Encrypt.
sudo orchardctl claimsudo orchardctl claim --url mangoPrints a single-use link that claims the instance and signs you in as the superadmin. It works without email.
--url overrides the address in the link. A bare name uses the scheme and port that the instance serves on. For example, --url mango becomes http://mango:8081 on a lan install that moved off port 80. Add the name with orchardctl hostname add first.
After the instance is claimed, this command only prints a link if there is no other way in. If a way in exists, the command refuses and names it:
This instance already has a superadmin, and a way to sign in as them.Use your passkey. This only mints a link when there is no other way in.A passkey on a superadmin, a superadmin password, configured email, or a configured identity provider each count as a way in.
Enter the same email address as before when you use a recovery link. A different address creates a second superadmin.
To sign in day to day, use login.
sudo orchardctl loginsudo orchardctl login --url mangoPrints a link that signs you in as the superadmin, or as the account in --email. The link is valid for 10 minutes and works once. A new link replaces any earlier one. It works with or without email configured.
--url builds the link with another address. The address must be one that Traefik answers on, which you can add with hostname add.
password
Section titled “password”sudo orchardctl password setsudo orchardctl password clearSets or removes a password on a superadmin account. On an instance with no email, --email can also name someone who joined by invitation link. Running set again resets the password. With more than one superadmin, add --email.
The command prompts for the password and turns off terminal echo, so the password stays out of the shell history and the process list. Orchard stores a bcrypt hash. The minimum length is 12 characters.
backups s3
Section titled “backups s3”To show or change the S3 storage for backups and uploads, use orchardctl backups s3.
sudo orchardctl backups s3 statussudo orchardctl backups s3 test --endpoint https://s3.eu-west-1.amazonaws.com --bucket my-bucket --region eu-west-1 --path-style false --access-key <KEY_ID>sudo orchardctl backups s3 set --endpoint https://s3.eu-west-1.amazonaws.com --bucket my-bucket --region eu-west-1 --path-style false --access-key <KEY_ID>sudo orchardctl backups s3 clearset tests the connection first and saves nothing if the test fails. To save without the test, add --skip-test. Both test and set ask for the secret key, or read it from --secret-key-file or ORCHARD_S3_SECRET_KEY. --secret-key also works, but it stays in your shell history.
clear removes the saved settings. Backups then go back to the store on the server, if the instance has one.
A change applies to new databases. For what happens to existing ones, refer to What happens when you change storage.
stop, start, and restart
Section titled “stop, start, and restart”sudo orchardctl stopsudo orchardctl startsudo orchardctl restartStops and starts the k3s service. This affects the dashboard, the API, your databases, and every app. Disks stay in place and nothing is deleted. Apps come back when the node does.
start waits for the node to report Ready. A reboot has the same effect as start.
restart restarts the cluster, not only the Orchard pods. To restart Orchard pods without restarting k3s, use update.
logs and status
Section titled “logs and status”orchardctl statusorchardctl logs # serverorchardctl logs frontendorchardctl logs mcpThese commands do not need root. logs keeps following until you press CTRL + C.
These commands show the control plane, not your apps. For an app’s logs, use the dashboard or the orchard CLI.
sudo orchardctl k3ssudo orchardctl k3s patchsudo orchardctl k3s upgrade| Command | Description |
|---|---|
orchardctl k3s |
Show the k3s version on this server, and what is available. |
orchardctl k3s patch |
Apply the latest patch of the current minor version. orchardctl update also does this. |
orchardctl k3s upgrade |
Move to the version on the k3s stable channel, one minor version at a time. |
Versions come from the k3s release channels, so a security patch does not wait for an Orchard release.
Each step does the following:
- Downloads the binary and checks it against its published checksum.
- Stops k3s, and copies its database to
/var/lib/rancher/k3s/server/db.previous. - Replaces the binary, and keeps the old one as
/usr/local/bin/k3s.previous. - Starts k3s, and waits for the node and the Orchard server.
If the node or the server does not come back, the command restores the old binary and database and stops. Apps keep running during a step, but the dashboard and API can pause.
To turn off automatic patches, add the following line to /etc/orchard/env. The installer adds it when you install with --k3s-version.
ORCHARD_K3S_UPDATES=offThe upgrade command does not run on its own, because a new minor version can change how a workload behaves. orchardctl update tells you when your version no longer gets security fixes. Take a backup of the control-plane database first.
The commands do not upgrade worker nodes. They list the nodes that are behind, so you can run the k3s install script on each one with INSTALL_K3S_VERSION. A cluster with more than one control-plane node is not upgraded. For that setup, follow the k3s upgrade guide.
images
Section titled “images”sudo orchardctl imagesShows the images Orchard bundles, and what each can move to. orchardctl update installs newer versions from their own registries, so a fix does not wait on an Orchard release.
| Images | What installs on its own |
|---|---|
| Redis, pgbouncer, BuildKit | Patch versions |
| VictoriaMetrics, vmagent, VictoriaLogs, kube-state-metrics, node-exporter, Vector, Trivy, versitygw, aws-cli, zot | Any version in the same major version, or in the same minor version below 1.0 |
| cloudflared | Any newer version |
A version below 1.0, such as Vector 0.61.0 or Trivy 0.76.2, treats a new minor version as a new major version. Each version that update picks waits until it has been public for 7 days, unless it fixes a known vulnerability in the running version. To fix a known vulnerability, a standalone tool such as Trivy or Vector can also move to a new minor version below 1.0. For the full rules, refer to Third-party update policy.
Each version that update picks is pinned to the digest that the registry served for it. Apart from cloudflared, a new major version needs a person. If a new version does not come up within three minutes, the update goes back and does not try that version again. To try it again, remove its line from /etc/orchard/images-held.
The versions go in /etc/orchard/images.yaml. An image that you set in /etc/orchard/values.yaml stays as you set it. To turn these updates off, add ORCHARD_ADDON_UPDATES=off to /etc/orchard/env.
sudo orchardctl syncCopies orchardctl from the running server image, for the host’s architecture, and re-creates the hyphenated links. Use it when documentation mentions a command that your host does not have yet. update runs this command at the end.
The command checks the download before it replaces the binary. The file must be at least one kilobyte and an ELF binary.
uninstall
Section titled “uninstall”sudo orchardctl uninstallRemoves the instance permanently. The command lists what it deletes, then asks you to type a phrase that names the instance, such as delete orchard.example.com. Any other input stops the command with nothing changed. No flag skips the question. A script can pipe the phrase in.
The command runs the following steps:
- Disables
orchard-update.timerand removes its units. - Runs
k3s-uninstall.sh, which deletes every app, database, and volume. - Removes the following paths:
| Path | Contents |
|---|---|
/etc/orchard |
The values file, which includes your secrets. |
/usr/local/bin/orchardctl and its orchard-* links |
These commands. |
/usr/local/bin/orchard-sync-commands |
The shell script that installs them. |
/usr/local/bin/helm, /usr/local/bin/yq |
Tools that the installer downloaded. |
/etc/rancher, /var/lib/rancher |
What remains of k3s. |
/var/lib/vector-orchard, /etc/cni |
Log checkpoints and CNI configuration. |
/etc/sysctl.d/90-orchard-builds.conf |
The kernel setting for rootless builds. |
~/.kube, and helm’s directories in ~/.config, ~/.cache, ~/.local/share |
Root’s kubectl and helm state. |
If k3s-uninstall.sh fails, the command stops and keeps orchardctl and the values file, so you can run it again.
The command does not remove database backups stored off this machine, your DNS records, or the rules that the installer added to ufw or firewalld.
Upgrade from the shell version
Section titled “Upgrade from the shell version”On a host that has the shell-script version of these commands, run sync twice:
sudo orchardctl sync # installs the new bootstrap scriptsudo orchardctl sync # installs the binary and links the aliasessudo orchardctl update also runs the bootstrap at the end, so an upgrade followed by one sync has the same result.
Use an image you built yourself
Section titled “Use an image you built yourself”Orchard releases sign the host commands, and orchardctl runs as root, so it refuses to replace itself with commands from an image that has no valid signature. It also keeps its current commands when the image is an older release. The update carries on either way and prints a note.
Images you build yourself are unsigned. The installer allows them when you pass a custom image registry, repository, or tag. To allow them on an existing host, add this line to /etc/orchard/env:
ORCHARD_ALLOW_UNSIGNED_COMMANDS=trueRelated resources
Section titled “Related resources”- Configuration - Learn where each instance setting is stored and which value takes precedence.
- Upgrade Orchard - Plan and run an upgrade on an installer host or a Helm install.
- Install - Run the installer again to change answers such as the ingress mode.