Apps
Run a project's web front end, API or database on one of your runners with hosting on, read its logs, browse its data and open its URLs.
A workspace's repositories often hold something you can run: a web front end, an API, a worker, a database. Yard runs them on a runner with hosting on and gives each one an address under that runner's domain, so there is no DNS to set up per app.
- The Apps page of the workspace (under More in the sidebar) runs the workspace's
own apps, from its copy of each repository as it is on the base branch.
Address:
<app>-<workspace>.<domain>. - Environments on the same page run those apps again under a name, such
as a staging copy, from a branch you choose for each repository. No project
is started for them. Address:
<app>-<environment>-<workspace>.<domain>. - The Apps view of a project runs a preview from the project's
worktree as it is right now (uncommitted changes included). Address:
<app>-<project>-<repo>.<domain>.
The Apps page
- Add app opens a form for the fields most apps set (kind, folder, commands, port) over the app's full setup as JSON. Either can be edited.
- Each repository lists its apps as rows: the name, what it is ("Service, port 5173"), where it runs from, its address with a link to open it, and its state. A database, or an app with no public port, reads Internal only, no address. Start and Stop are on the row; Restart, Logs, Terminal, Edit, Reset and Remove are in its menu. Terminal opens a shell inside the app's container while it runs (not offered for a database). The repository's own menu has Add app here, Save as org default and Set up with the agent.
- Hosted on names the runner. With more than one to choose from, it is a list: pick a runner, or leave the choice to Yard. An official runner with hosting on is in the list too, marked (official), when your plan includes it; Yard falls back to one when none of your own runners hosts.
- Domain lists the domains the workspace can use: every verified domain
of the runner that hosts, and
yrd.shwhen that runner has the free subdomain on. Each row says where the domain is set up and how it is reached. Pick one and the apps get their addresses under it at their next start. A domain that belongs to another runner than the one hosting (the edge'syrd.sh) reads Proxied by that runner, with a note that the extra hop can make the apps slower. Open runner settings opens the hosting runner's settings, where domains are added. - Environments lists the workspace's environments: each one's name, the branch of each repository, and how many of its apps run. New environment asks for a name and a branch per repository (the base branch first, then the branches on the remote), and starts its apps unless you untick Start its apps now. Click a row to list its apps, with the same Start, Stop, Logs, Terminal and Reset as above; the number on a row opens that app's env in this environment. The row's menu has Rename, Change branch (running apps restart on the new one) and Delete. See Environments.
- Project previews lists what open projects run, with a link to each project. Who can open them sets who can open a preview started from now on: Team sign-in or Anyone with the link. A port or an app that names who can open it keeps that.
- Environment holds the values every app and preview starts with.
A workspace app needs the workspace's runner on 0.24.0 or newer, and a second domain needs the hosting runner on 0.24.0 or newer. An older runner still runs project previews under its default domain, and Yard says which runner to update.
Environments
An environment is a second (or third) copy of the workspace's apps, for a staging site or for a branch someone pushed, without starting a project.
- The same apps. It runs the apps the workspace has, with their setup. Only env values can differ: those set in an app's env from the environment's row win over the workspace's, for that environment alone.
- Its own branch. Each repository runs the branch you chose, as it was last fetched from GitHub. When a fetch moves that branch, the environment's running apps restart with it; stopped apps stay stopped. On the base branch, it follows the base branch like the workspace's own apps. A branch deleted on GitHub leaves the apps running on what they have, and the row says Branch gone until you choose another.
- Its own addresses and data. Its apps are at
<app>-<environment>-<workspace>.<domain>, on a network of their own, with their own database volumes and credentials. Resetting or deleting an environment never touches the workspace's own apps or another environment. - Delete takes its apps down and removes their data and the environment's env values.
A workspace has at most 10 environments. An environment on another branch than the base needs the workspace's runner on 0.50.0 or newer; Yard says so on its row when the runner is older.
Turn on hosting
Hosting is a feature of a runner. An organization admin (or the owner of a personal runner) turns it on in Settings → Runners → the runner → Hosting. The runner needs Docker; it then starts a proxy (Traefik) on its machine by itself.
An instance can also offer official hosting: an official runner with hosting on runs apps of every organization its tier allows, each app on its project's own network, up to a number of apps per organization the instance admin sets. Instance admins turn it on in Admin → Runners → Hosting, or keep a runner's hosting when they make that runner official.
-
A domain of your own. Enter a domain, say
apps.example.com, and create the records Yard shows at your DNS provider:Record Value _yard-verify.apps.example.comTXT"yard-verify=<token>"apps.example.comA/AAAA(orCNAME)your server *.apps.example.comA/AAAA(orCNAME)your server Then press Verify. The status shows pending, verified or failed with the last error. Apps get URLs on the domain only once it is verified. Yard checks the record again every day; if it is gone three days in a row, the domain goes back to pending, its URLs keep working for seven more days, and the organization's admins are told. A domain someone else has verified, or a parent or subdomain of it, cannot be added.
-
More domains. Add a domain gives the runner another domain, verified the same way. Each verified one serves apps; the first is the default, and a workspace picks the one its apps are under on its Apps page. Remove gives a domain up.
-
TLS:
http01(Let's Encrypt; port 80 must be open),dns01(one wildcard certificate through Cloudflare; needs a token file on the machine),manual(your own certificate files), oroff(something in front serves https). The machine's side is set withyard runner hosting set. -
Free subdomain on yrd.sh. No domain needed: each app gets
https://<app>-<id>.yrd.sh. Choose Tunnel (no open port), where the runner connects out to Yard's edge, or Proxy to this address, where the edge connects to your server's public address. The edge only forwards traffic: your apps always run on your runner. An org admin can switch to readable names,<app>-<repo>-<org>.yrd.sh, in Organization settings → General. -
Max apps caps how many apps the runner runs at once. The section also shows the live state: proxy, ports, certificate, Docker, tunnel. When hosting cannot start, it and a refused start say why: Docker is not available (with the reason), or the proxy could not start (with its error, for example the container that already holds port 443). The runner tries again by itself. A runner in a container or behind Coolify: Connect a runner.
-
Use for workspaces off makes a hosting-only runner: it gets no workspaces. Use it when you would rather not have an internet-facing proxy on the machine that holds your workspaces' files.
Yard's own runners never run your apps. A workspace's apps run on the runner picked under Hosted on on the workspace's Apps page; without a choice, on the workspace's own runner if it hosts, else on another of the organization's runners with hosting. With none, the Apps tab says to turn on hosting on one of your runners. A personal runner runs apps only for workspaces on it or created by its owner.
When the app runs on the same runner as its workspace, the source is copied on the machine. On another runner it travels through the organization's storage bucket.
Running apps
A project's Apps tab shows its apps, with the address, the state and a link to open each:
- 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>, orhttps://<app>-<port>-<project>-<repo>.<domain>when an app has several. With free subdomains on, it also has a name onyrd.shthat stays the same across restarts. Each URL says whether it is on your domain or on yrd.sh.
An app is team by default, on yrd.sh too: 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.
Limits on yrd.sh
Starting an app that gets a name on the edge (yrd.sh, or a domain through
the edge) needs a license, owners included: without one it
is refused with 402 plan_required. Apps on your own domain, without the
edge, need none.
Free names are limited per organization: 10 names, and 10 GB a month through
the edge (the organization's Usage page shows it). Each name takes up to
1200 requests a minute, and each visitor's address up to 300; over a limit
the answer is 429 and the visitor retries later. Request bodies are capped
at 50 MB. Starting an app that would need an eleventh name is refused: reset
an app you no longer need first (resetting without keeping data frees its
name). The Yard team can suspend a name or an organization that is used for
abuse; it then answers "not found".
Names on yrd.sh share one domain, so until yrd.sh is on the Public Suffix
List an app there should not rely on its cookies being private from other
apps on yrd.sh. Use a domain of your own for apps with sign-ins of their own.
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 repository's menu on the Apps page: 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 | 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.
A project with apps of its own says so: its Apps tab is marked Only here, and the tab opens with a banner, "N apps only in this project", and Promote to workspace, which moves all of them to the workspace layer (each app's row keeps its own button too). Once they are promoted, every project of the workspace sees them and the marker goes away.
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):
- what Yard sets itself:
PORT,HOST,PUBLIC_URL,YARD_HOSTING_DOMAIN(the domain your app's address is under),YARD_HOSTING_DOMAINS(every domain your apps may be served under, comma-separated), the URLs of the other apps of the repository, and each database's URL in the variable the app names for it; - the app's own defaults;
- the workspace's values (Environment on the Apps page);
- 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 sealed in your browser to
your organization's vault: only its runners can open it, Yard's servers cannot. The runner fills it in when the app starts. It is 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 the URL of another app of the same repository.
Dev servers and allowed hosts
Vite, SvelteKit, Next.js, Webpack and Angular dev servers refuse hosts they
do not know, and show "Blocked request. This host is not allowed" at your
app's address. Read YARD_HOSTING_DOMAINS in the project's config to allow
them all, so a domain you add later works without a code change. For Vite:
const domains = (process.env.YARD_HOSTING_DOMAINS ?? "").split(",").filter(Boolean);
// in defineConfig: a leading dot allows the domain and its subdomains
server: { allowedHosts: domains.map((d) => `.${d}`) },
Calling another app from the browser
A web front end runs on its server and in the visitor's browser, and only the
server can reach another app by its internal name. A variable the browser
reads (PUBLIC_*, VITE_*, NEXT_PUBLIC_*) should hold {{app.api.url}},
the other app's public address, never localhost or an internal name. That
app must allow the web app's address (CORS). If the target is a team
app, the browser has no sign-in cookie for the other host and the call fails
like a CORS error; the first lines of the app's log say so when a browser
variable points at a team app. Serve it from the same address instead: the
app's setup can forward a path of the web app's port to a sibling app.
See what an app gets
Open an app's settings (Edit on its row). Under the form, Environment lists every variable that app runs with and where each value comes from:
| Group | What is in it |
|---|---|
| Needs attention | a secret nobody has typed yet (Needs a value), and a link to an app that does not exist |
| This app's own values | values set for this app only |
| Inherited | values for all apps or for the repository |
| From the app's config | the app's defaults, including links such as {{app.api.url}}/api/v1, shown with the address they resolve to |
| Databases | the URL of each database the app binds |
| Set by Yard | PORT, HOST, PUBLIC_URL, YARD_HOSTING_DOMAIN(S) and the other apps' addresses |
Press Set or Change on a row to give this app its own value: paste a secret, type a value, or pick Link to app to insert another app's URL. It is saved at once for that app only, in the workspace (on the Apps page) or in the project (in a project's Apps tab, where it wins over the workspace's), and applies at the app's next start. The × on one of the app's own values removes it, and the app gets what it inherits again. Variable adds a new one.
A row in the list of apps shows how many variables still need attention
("2 need a value"); pressing it opens that app's Environment. An app with
missing values still starts, and the first line of its log says what is
missing, for example
missing: API_TOKEN (needs a value).
Environment on the Apps page (and the Env panel of a project) is the place for values shared by all apps or by a repository. It is grouped by what each value applies to, and an app's group has a button to that app's own list.
The agent
Set up apps asks the agent to propose the apps. Start it from the Apps page (Set up with the agent) or from a project's empty Apps tab: either way the message starts a project of its own, called Set up apps. Started from a project, the message names that project.
The agent reads the repositories, checks what the workspace already has
(yard app config show), and proposes the apps. However many it proposes,
the chat shows them as one card with their names and how many are saved,
skipped and waiting. Configure apps on it opens a dialog with the list of
apps and, beside it, the one you picked: its name, repository and kind, the
setup, build and start commands, the ports and who may open each URL
(Team or Public), the health check, what it depends on and which
databases it binds, its Env and its Secrets. Edit any field, or
Edit as JSON for the rest. Nothing
is saved until you press Confirm, which saves the app as you edited it to
This project (offered when the setup named one) or the Whole
workspace, and moves on to the next app that waits. Skip leaves it out;
Confirm all saves every app still waiting, and stops at one that is
refused. What was saved or skipped stays on the card and in the dialog, for
everyone in the chat and after a reload; viewers see the apps without the
buttons.
The agent fills in the env it finds in the code and its env examples:
- Links to other apps. A URL that points at another app of the
repository is written as a link, for example
PUBLIC_API_URL={{app.api.url}}/api/v1on a web app andAPP_URL={{app.web.url}}on its API. The card shows where it points ("→ api URL"), and the real address is filled in when the app starts. - Databases and Redis are bound to a database app, so their URL is never typed.
- Secrets are listed by name, never with a value. A key the app makes for itself (an encryption key, a session secret) is Generated on save: Yard creates it when you confirm, stores it sealed and shows it to nobody. Press I'll paste my own to set it yourself instead. A key only you have (a payment provider's, say) reads You set this after saving and shows on the app as Needs a value until you type it.
- Optional keys the app runs without are left out; the agent names them in its reply.
Confirming again does not replace a secret that already has a value.
A goal's agents propose apps the same way, as its projects need them. The goal's Settings list what they propose as a diff against what the repository runs now (A for a new app, M for a changed one), with Apply and Reject; it never reads a secret's value. On Autopilot, with app changes not on its "always asks" list, the goal saves them itself, except one that needs a secret only you can type: that waits, and you get a notification.
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; yard app env <repo>/<app> prints what
an app runs with, where each value comes from and what is missing, with
secrets masked. To set up or change an app it proposes
it the same way; it saves one directly with
yard app config set <repo> <file.json> (project layer only) only when you
ask it to. yard-shot url <app url> signs in to a team app by
itself, and yard app ticket <url> prints a header for curl (for a
port preview of the box too). The agent can only reach its own
project's apps.
A server the agent only starts in its box (bun run dev) needs no app: it
opens as a port preview, from the chat or the project's Ports
view. To hand it to someone else, publish the port:
it gets an address of its own on the runner that holds the box, for the team
or for anyone, until the process stops, the box stops or it is unpublished.
The Apps tab counts published ports with the running apps.