Apps

A project's repositories often hold something you can run: a web front end, an API, a worker, a database. The Apps tab of a project runs them on a hoster, from the project's worktree as it is right now (uncommitted changes included), and gives each one a URL.

A hoster is a machine with a domain of its own, registered on the organization's Hosters page (see the CLI reference, yard hoster). Apps never run on the runner that holds your files: the hoster gets a packed copy of the worktree, which travels through the organization's storage bucket.

Running apps

In the Apps tab:

• Start all starts every app, the ones others depend on first. Stop all stops them; their data stays.
• Each app has Start or Stop, Restart (rebuilt only when the files changed), Logs (build and run, live) and, for a database, Browse data: its tables, their rows page by page, and a query box. Queries are read only: a query that writes is refused.
• Reset… removes an app's container, image and logs. Without Keep data, a database's volume and credentials go too, and it starts empty next time.
• Each public port of an app has its own URL: https://<app>-<project>-<repo>.<domain>, or https://<app>-<port>-<project>-<repo>.<domain> when an app has several.

An app is team by default: opening its URL asks for a Yard sign-in, and only people who can see the project get in. A port can be made public instead.

Closing a project stops its apps. Deleting a project removes them, with their data.

Where app setups live

App setups are stored in Yard, never in the repository, in three layers. A lower layer replaces an app of a higher one as a whole.

Layer	Who edits it	What it is for
Org default	org admins	Save as org default in a workspace's settings: every workspace with the repository starts with these apps.
Workspace	workspace members	The source of truth: every project of the workspace sees the same apps.
Project	project members, the agent	Try a new app, or a change to one, on one branch. Promote to workspace when it is ready.

Since every project sees the workspace's apps, an app added in one project shows up in the others at once. A project whose branch does not have the app's folder (or its Dockerfile) shows it as Not on this branch, and it cannot be started there until that branch has the change. An inherited app can be hidden in a workspace or a project.

An app's kind says how it runs: service (setup, build and start commands in a base image), static (build once, then serve a folder), dockerfile, or database (Postgres, MySQL or Redis, with a volume of its own).

Env variables

An app runs with, in this order (the later one wins):

1. what Yard sets itself: PORT, HOST, PUBLIC_URL, the URLs of the other apps of the repository, and each database's URL in the variable the app names for it;
2. the app's own defaults;
3. the workspace's values (workspace settings → Apps);
4. the project's values (the Env panel of the Apps tab).

There are no personal values: whoever starts an app, a person or the agent, it gets the same env. A value can be secret: it is stored sealed, shown masked, never sent back by Yard, and kept out of logs. In a value, {{secret:NAME}} is filled in with a secret value called NAME, and {{app.<name>.url}} with another app's URL.

The agent

In a project, the agent can run the project's apps with the yard command in its box: yard app list, start, stop, restart, reset, logs, db tables, db rows and db query. It can propose an app with yard app config set <repo> <file.json>, which saves it for that project only; a person promotes it. Set up apps in an empty Apps tab asks the agent to do that. yard-shot url <app url> signs in to a team app by itself, and yard app ticket <url> prints a header for curl. The agent can only reach its own project's apps.