# What runs on your machines

What runs on an app's machines and build machines, what the platform sees of them, and how they behave when something fails.

## The machines

An app's machines are ordinary compute instances in your organization's private network: they
appear under **Compute**, one per replica, and app machines join the default network. Each machine
runs an agent and your containers under Podman. The agent signs in to the platform as an IAM user
that belongs to the app, with its own access keys and policies; deleting the app deletes that user.

The agent fetches what the machine should run (the deployment, its image or pinned compose file, and
the decrypted environment), pulls the images, starts the containers and reports back. The
deployment's **Activity** marks each line as reported by the machine itself or written by the
platform. Machines fetch a newer agent every 15 minutes.

## How containers get their configuration

- The environment is handed to each container in a file, so a long list of variables costs nothing
  at start.
- A value with line breaks (a PEM key, a service-account JSON) is handed over as a Podman secret of
  type `env` instead of a line in that file; the container sees an ordinary environment variable.
- The platform's CA is mounted read-only at `/etc/ews/ca/platform-ca.pem` into every container the
  agent starts (the app, each compose service, the release command, scheduled jobs), and
  `NODE_EXTRA_CA_CERTS` (and, beside an unprefixed database binding, `PGSSLROOTCERT`) point at it;
  see [Bind a managed database](bind-a-database.md#trusting-the-database-s-certificate).
- `PORT` is set in the container (since 2026-11-15).
- The release command runs in a throwaway container of the new image, removed when it ends.
- A named volume is a volume on the machine's disk; it survives redeploys but not replacing or
  destroying the machine, and it is never removed.

## Build machines

An app built from a repository is built on a temporary machine of its own, started for each
deployment, which runs BuildKit (or Railpack), pushes the image to your registry and is deleted once
the image is pushed. Its time is not billed to you; if you bring your own cloud account, it runs and
is billed there. The builder sends its log to the platform every two seconds. A build is stopped
after 15 minutes. Deleting an app also deletes a build machine still running.

## What the platform sees: desired versus live

About every 30 seconds the machine's agent sends a redacted summary: each container with its image,
state and published ports, the names of its environment variables, and the routes it serves. Values
never leave the machine: each one is replaced by a keyed hash (HMAC-SHA256 under a per-app key that
only the platform and the app's machines hold), and the platform hashes the values it sent the same
way. Selecting a machine on the **Resources** tab compares the two and lists each difference, for
example `container is exited, not running`, `env DATABASE_URL differs`, `port 8080 is not
published` or `no route for shop.example.com`. Environment variables are compared only for someone
with `deploy:ManageEnv`.

```sh
dcloud deploy apps live-diff app-id --instance instance-id
```

The answer's `state` is `match`, `differs` or `unknown`. A machine whose agent has not sent a
summary yet shows **Unknown**; a machine created before September 2026 has no agent update that
sends it and shows **Unknown** until it is replaced. The comparison also catches what sync cannot: a
container started before the platform began to set something (for example `PORT`, set since
2026-11-15) is in sync by generation but reads `env PORT is not set` until its next deployment.

## Scheduled jobs

The machine keeps the schedule itself, so runs happen while the control plane is unreachable; only
their results wait until it answers again. An app with several machines runs each job on exactly one
of them: machine 1, or, when machine 1 has not reported for three minutes, the next machine that
has. When machine 1 reports again the jobs move back. A machine cut off from the control plane keeps
running its jobs, so in that case a run can happen on two machines: write jobs that are safe to run
twice. The **Scheduled jobs** tab says which machine runs the jobs.

## How failures behave

| What fails                                      | What happens                                                                                                                                             |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The release command exits non-zero or times out | The deployment fails; the previous version keeps serving (default timeout 10 minutes)                                                                    |
| The new container never passes its health check | The deployment fails; the old container keeps serving (image apps run old and new side by side until the new one answers)                                |
| A registry login is refused                     | The machine retries until the deployment times out; the activity says _Rollout attempt failed, retrying: registry login …_                               |
| A build fails                                   | The deployment ends at once with the build's last lines                                                                                                  |
| Machines do not report healthy within 8 minutes | The deployment is `failed` (20 minutes when the deployment created a new machine)                                                                        |
| A machine stops reporting                       | Its health becomes not reporting after a minute, its sync unknown; a job run it had not finished 15 minutes past the job's timeout is recorded as `lost` |
| A machine stays out of sync after a rollout     | After a minute it is written to the app's and the machine's events (phase `drift`)                                                                       |
| The control plane is unreachable                | Containers keep running and scheduled jobs keep firing; results are delivered when it answers again                                                      |
| A compose service changes on redeploy           | That service is down for the seconds it takes to start; unchanged services keep running                                                                  |

## Logs

Your containers ship what they print: lines appear in the app's **Logs** tab about ten seconds after
the container writes them. See [Monitoring](monitoring.md).

## Related

- [Inspect an app](inspect-an-app.md)
- [Deployments](deployments.md)
