Skip to content

Deployment Models

A managed install receives its configuration from one or more sources. There are three ways to apply managed configuration, and they compose: a provisioning profile bootstraps trust, a central signed policy delivers the live policy over the network, and a machine policy applies a policy from a trusted local path. This page explains each model, when to use it, and how the sources combine.

For the policy document schema, see the Policy Schema Reference. For standing up the server that serves a central policy, see Policy Server Deployment and Operation.

The three models

Machine policy

A machine policy is an unsigned EnterprisePolicy JSON document placed at an administrator-writable local path. It is trusted by that path: the path is the trust boundary, so the policy needs no signature. Backend.AI GO looks for it in order:

  • The AIGO_POLICY environment variable.
  • ./aigo-policy.json in the working directory.
  • ~/.config/aigo/policy.json in the user config directory.
  • /etc/aigo/policy.json (Unix system path).

Use a machine policy for a single machine, a lab, or a deployment that an MDM tool or configuration manager already controls by writing files. It applies as a mandatory layer and locks the settings it targets. It requires no network and no policy server.

Central signed policy

A central signed policy is an Ed25519-signed SignedPolicy document fetched from the policy server over the network, verified against the provisioning trust anchors, polled on an interval, and cached locally. Trust comes from the signature, not the path, so the document can travel over an untrusted network.

The verified policy is cached at <app_data>/enterprise/central_policy.json and re-verified against the trust anchors at every load. The device polls the server at the interval returned during enrollment (pollIntervalSecs), comparing the cheap policy version first and downloading the full document only when the id changes.

Use a central policy for a fleet that must receive policy updates without touching each device. It applies as a mandatory layer and locks the settings it targets.

Provisioning profile

A provisioning profile binds a device to an organization and bootstraps the other two models. It carries the trust anchors (the public keys that verify the central policy and the offline license), the management server URL, an optional bootstrap egress firewall installed before any network call, and an optional one-time enrollment token. Discovering a profile is what puts the install into managed mode.

Backend.AI GO discovers a profile from, in order, a CLI flag or environment variable, an aigo://enroll deep link, an OS managed path (an installer or MDM drop), or the cached profile from a previous run. The verified profile is cached at <app_data>/enterprise/provision.json, with any one-time token stripped after first use. Device onboarding is covered in Device Enrollment and Trust Anchors.

How the sources combine: ConfigSource precedence

Effective settings are resolved by layering each source as an RFC 7386 JSON merge patch over the user's settings, in a fixed precedence order. The source of each setting is reported as a ConfigSource:

Priority ConfigSource Wire value Locks? Origin
1 (lowest) Builtin default builtin_default No Compiled-in defaults
2 Recommended recommended No Advisory layer that fills gaps only
3 User settings user_settings No The user's own settings
4 Machine policy machine_policy Yes Unsigned local policy at a trusted path
5 (highest) Central policy central_policy Yes Ed25519-signed policy from the server

Higher priority wins. A recommended layer only fills settings the user has not set; it never overrides a user value and never locks. The two policy sources are mandatory: they override the user value and lock every path they touch.

Only machine_policy and central_policy lock a setting. A locked setting cannot be changed by the user: the input is disabled and carries a "Managed by your organization" badge, and a user-originated write to it is rejected by the backend, not silently dropped. When both a machine policy and a central policy target the same path, the central policy wins, because it is the highest-priority source.

The merge-patch and lock mechanics (how settingsOverrides and lockedPaths target settings) are the same for every source and are documented in the Policy Schema Reference.

Inspect the resolved state

Both transports expose the resolved managed state from one shared service: the Tauri command get_managed_status and the REST route GET /api/v1/enterprise/status. The status reports whether the install is managed, the organization label, a source map (which ConfigSource decided each managed path), the set of locked paths, the egress posture, and the offline-license state.

In the app, the same information appears under Settings, in the Organization tab: the enrollment status, the locked-setting count, the egress posture, the air-gapped indicator, and the license badge. An un-managed install reports managed: false with empty maps and an unenforced egress, so its behavior is unchanged.

Choosing a model

The models are not exclusive. A typical fleet uses all three: a provisioning profile to enroll and establish trust, a central policy for the living configuration, and (optionally) a machine policy for a baseline that holds even before the first poll.

Need Use
One machine or a lab, configured by file Machine policy alone
A fleet that receives policy updates centrally Provisioning profile plus central policy
A baseline that holds before the first central poll Machine policy plus central policy
A fully offline managed install Machine policy with air-gapped mode (see Air-Gapped Deployment)

Application data directory

The cached central policy, provisioning profile, device identity, and offline license live under the application data directory:

  • Linux: ~/.local/share/ai.backend.go/enterprise/
  • Windows: %APPDATA%\ai.backend.go\enterprise\
  • macOS: ~/Library/Application Support/ai.backend.go/enterprise/

These are per-user caches written by the app. The administrator-managed inputs (the machine policy and the provisioning-profile drop) live at the OS paths listed above and in Device Enrollment and Trust Anchors.

Next steps