
<div class="callout callout-attn"><p><strong>Alpha.</strong> VIA is under active development. APIs, operational flows, and host requirements may change between releases.</p></div>

Via runs Vary apps on one Ubuntu host. It owns the path from source intake through tests, artifact signing, runtime launch, configuration delivery, add-on bindings, domain policy, and public routing.

Operators manage the host with `via`. App owners deploy and inspect apps with `vary`.

```mermaid
flowchart TB
    WORKSTATION[App owner workstation] -->|vary app deploy| INTAKE[Via HTTP + Git endpoints]
    INTAKE --> CONTROL[Control plane]
    CONTROL --> BUILDER[Builder]
    BUILDER --> ARTIFACTS[Signed artifact store]
    ARTIFACTS --> RUNNER[Runner]
    RUNNER --> RUNTIME[Docker runtime container]
    RUNTIME --> CONFIG[Config server]
    CONFIG --> ADDONS[Add-ons + secrets]
    CONTROL --> ROUTES[Domain + route policy]
    ROUTES --> PROXY[Managed public proxy]
    PROXY --> RUNTIME
    CONTROL --> STATE[(Control-plane state)]
    BUILDER --> STATE
    RUNNER --> STATE
```

## Service roles

The main Via services are installed as systemd units. Each service has a narrow job and reports health through `via status` and `via doctor`.

| Service | Role |
|---|---|
| Control plane | Owns apps, users, sessions, releases, operations, audit, source intake, domains, routes, and add-on state. |
| Builder | Checks out source, typechecks, tests, packages, and signs Vary app releases. |
| Runner | Verifies signed artifacts, starts runtime containers, promotes healthy deploys, and records runtime state. |
| Config server | Serves authorized config, secret values, and add-on descriptors to running apps. |
| Proxy | Publishes approved public routes to the current healthy runtime target. |
| Test runner | Runs queued app test jobs and records results. |

## Control-plane state

The control plane is the source of truth. It records app identity, release history, build state, runtime state, config profile versions, bindings, domains, routes, operations, audit, and backup metadata.

Worker services report mutations through internal control-plane APIs instead of each daemon independently writing platform state. That keeps build, deploy, route, and runtime transitions ordered and auditable.

For operator debugging, `via doctor` reports writer role, SQLite journal mode, busy timeout, and internal API compatibility.

## Host components

Via uses host components, but operators should change Via state through `via` and `vary` commands rather than hand-editing generated files or container state.

| Component | Used for | Managed by |
|---|---|---|
| systemd | Starts and supervises Via services. | Host OS and `via install`. |
| Docker | Runs Vary build jobs and app runtime containers. | Docker daemon, with Via creating and supervising containers. |
| Git HTTP backend | Accepts app source pushes over the Via-hosted Git endpoint. | Ubuntu `git` package, invoked by the control plane. |
| SQLite | Stores platform state such as apps, releases, users, operations, audit, routes, domains, bindings, and add-ons. | Via state directory. |
| Vary toolchain | Typechecks, tests, compiles, and packages Vary apps during builds. | Via toolchain store and builder environment. |
| Public proxy | Terminates HTTPS and routes approved public traffic. | Host package plus Via-managed service/config/state. |

## Storage layout

Via keeps durable server state under the Via state directory and host configuration under the Via config directory. The exact paths can be configured, but the default layout is what most installations use.

| Area | Default path | Contains |
|---|---|---|
| Config | `/etc/via/` | Server config, routing policy, generated proxy config. |
| State | `/var/lib/via/` | Control-plane database, identity keys, source repositories, artifacts, build state, runtime state, add-ons, toolchains, and proxy state. |
| Logs | `/var/log/via/` | Service log files that mirror the systemd journal. |

Backups are based on this split. A normal backup captures config, database state, identity material needed for verification, repositories, artifacts, and add-on data. Secret recovery material is opt-in because it can decrypt protected app values.

## Deploy lifecycle

A deploy starts on the app owner's workstation. It finishes after Via has tested, built, signed, verified, launched, configured, and routed the app. The previous healthy runtime keeps serving if a new build or deploy fails.

| Stage | Owner | What happens |
|---|---|---|
| Source push | App owner | `vary app deploy` pushes committed source to the server-hosted Git endpoint. |
| Intake | Control plane | The server authenticates the push, validates the target app and ref, and records a queued deploy. |
| Build | Builder | The builder checks out source, typechecks, tests, compiles, packages, and signs the artifact. |
| Artifact | Control plane | Signed artifact metadata is recorded with the deploy and build result. |
| Launch | Runner | The runner verifies the signature and starts or supersedes the runtime container. |
| Bind | Config server | Runtime config, secrets, and add-on descriptors are authorized for the running release. |
| Route | Proxy | Approved domains and routes point to the healthy runtime target. |

Via separates deployment from public routing. A successful deploy proves that the server built and launched an app. A route proves that the hostname is allowed, verified, approved when required, covered by a certificate, and free of conflicts.

## Runtime boundary

App runtimes run in Docker containers launched by Via. Runtime access is intentionally narrow:

| Boundary | Rule |
|---|---|
| Artifact | Runner starts only a verified signed artifact. |
| Identity | Runtime gets a short-lived workload token. |
| Config | Runtime asks the config server for authorized keys. |
| Add-ons | Runtime fetches descriptors by binding name. |
| Traffic | Public routes point only at the current healthy runtime. |
| Inspection | App owners use `vary app status`, `inspect`, and `logs`; no host shell is required. |

## Config and add-ons

The config server is the boundary between a running app and protected runtime material. Plaintext secret values are not written into source, build logs, image layers, deploy commands, app-owner status output, or route metadata.

Add-ons are resources attached to apps through named bindings. A deploy snapshots the binding set, and the running app fetches descriptors by binding name.

| Add-on concern | Via behavior |
|---|---|
| Storage | Resource data lives under Via-managed state. |
| Binding | Operators bind a resource to an app under a stable name such as `DATABASE`. |
| Runtime access | Apps request the descriptor by binding name through the config server. |
| Credential rotation | Via can rotate descriptor credentials while keeping the app-facing binding name stable. |
| Snapshot and restore | Operators use Via add-on commands so state, audit, and runtime safety stay consistent. |

Continue to [Deploy lifecycle](/docs/via/deploy-lifecycle/) for deploy phases, [Add-ons](/docs/via/addons/) for the managed resource model, [Domains and routes](/docs/via/domains-and-routes/) for public traffic policy, or [Services and logs](/docs/via/daemons/) for service-level operation.