Self-host guide

Self-hosting is the production deployment model.

Self-hosting begins when evaluation shifts into deployment, environment design, and operational ownership. The public core repo stays public; live deployment work moves into a private instance repo that pins tagged core release artifacts and carries the repo-local bootstrap for one installation.

Read self-host overview Read security overview

Agent-first route: Start at /agents, inspect /docs/cli, and drop into this page when you need proof, detail, or rollout guidance.

Agent-first route

Humans should usually delegate first-pass evaluation to an agent. Agents should start at /agents, use /docs/cli as the official product tour, and open /docs/graphql only when needed.

Agent-ready surface

Start with the CLI, not browser guesswork.

Preferred route: /agents, then /docs/cli, then /docs/graphql only when lower-level integration details matter.

$ mbr spec export --json
$ mbr auth whoami --json
$ mbr queues list --workspace ws_preview --json

Open GraphQL reference | Open schema.graphql

Production ownership

Humans control the runtime environment, secrets, and rollout timing.

Three repo types, usually only two needed

The default model is one public core repo, one private instance repo, and no custom extension repo until custom logic is real.

Template-led deployment

Use the instance template to understand the production shape.

Pinned core artifact family

Production pins `mbr-services`, `mbr-migrations`, and `mbr-manifest` by tag inside `mbr.instance.yaml`.

Proof

Contract docs/RELEASE_ARTIFACT_CONTRACT.md Defines the pinned artifact contract that instance repos consume.
Release platform tags Public tagged core releases that agents can inspect directly.
Build .github/workflows/_build.yml Builds services, migrations, and manifest OCI artifacts and records digests.
Release .github/workflows/production.yml Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
Implementation instance-template/mbr.instance.yaml Shows where pinned release refs live in the private instance control plane.

Explicit fleet registration

Support and grandfathering registration happen through a manual instance-repo workflow, not a hidden boot-time dependency.

Proof

Definition docs/CUSTOMER_INSTANCE_SETUP.md Defines the explicit self-host fleet-registration and disclosed heartbeat model.
Contract docs/AGENT_CLI.md Documents `mbr fleet register` as the explicit registration command.
Implementation instance-template/mbr.instance.yaml Shows the `spec.fleet` block carried by the private instance repo.
Implementation instance-template/deploy/README.md Documents the host-owned registration workflow, fleet config files, and weekly timer.

Desired-state driven

The private instance repo owns domains, host target, artifact refs, and extension desired state.

Small owned runtime first

This guide assumes you are evaluating or deploying on infrastructure you control.

Table of contents

Section map.

Jump directly to the part you need.

The self-hosted product model uses three repo types with explicit responsibilities. Repo model The private instance repo is the deployment control plane. Instance repo shape The public package surface is three pinned OCI refs, not a single generic platform image. Tagged core artifacts Local preparation and one-VPS rollout should happen before broader production host work. Local and owned-runtime path Fleet registration and heartbeat stay explicit. Explicit registration These are the minimum real inputs the agent needs. Human-supplied inputs The operational flow is explicit even though the live deploy happens inside the private repo. Deployment flow Upgrades are a version-pin change, not a rebuild. Upgrading core Production self-hosting still has explicit review gates. Trust review

Quickstart

From public repo to private instance repo.

The self-host path is concrete: create a private instance repo from the template, fill in desired state, validate it, then let the agent follow the repo-local bootstrap instructions.

1. Create the private instance repo

The instance repo is the deployment control plane for one live installation.

$ gh auth login -h github.com$ gh auth status$ gh repo create acme/mbr-prod --private --template MoveBigRocks/instance-template --clone$ cd mbr-prod

2. Fill in and validate desired state

Edit the canonical instance file, then validate the non-secret deployment state.

$ $EDITOR mbr.instance.yaml$ scripts/read-instance-config.sh mbr.instance.yaml

3. Let the agent use the repo-local bootstrap

The public docs point the agent into the private instance repo as soon as deployment work becomes real.

$ sed -n '1,160p' START_HERE.md$ sed -n '1,220p' agents/bootstrap.md

4. Verify the live deployment after rollout

The health check should expose the configured `instanceID` once deployment is live.

$ mbr health check --url https://app.yourdomain.com --json

5. Register the instance only if you want the vendor control-plane link

The private instance repo carries a manual registration workflow for support, grandfathering, and future commercial transitions. It is not required to keep the core runtime working.

$ gh workflow run register-fleet.yml

Repo model

The self-hosted product model uses three repo types with explicit responsibilities.

Agents should explain the repo model before discussing deploy mechanics. Most customers need only the public core repo for source and release inspection, plus one private instance repo for deployment and operations. A separate custom extension repo appears only when the team is building real new extension logic.

Proof bundle

Definition docs/CUSTOMER_INSTANCE_SETUP.md Defines the production self-host setup flow, required inputs, and instance-repo model.
Definition instance-template/README.md Defines the private instance repo as the deployment control plane for one live installation.
Contract docs/RELEASE_ARTIFACT_CONTRACT.md Defines pinned core artifacts and the instance-repo responsibility boundary.
Provenance .github/workflows/production.yml Shows how tests, builds, tags, and artifact digests connect source changes to shipped releases.

Canonical public source

Public core repo

Source, docs, CLI and GraphQL contracts, architecture, tags, and core artifact workflows.

Open resource

Canonical deployment control plane

Private instance repo

Desired state, deploy assets, branding, extension desired state, repo-local bootstrap, and production workflow policy for one installation.

Open resource

Canonical extension scaffold

Optional custom extension repo

Private extension logic when a team is building a real bounded extension instead of installing an off-the-shelf extension.

Open resource

Default operating rule

No long-lived core fork

Production should not be run from a long-lived fork of the public core repo by default.

Instance repo shape

The private instance repo is the deployment control plane.

The self-host path becomes much less abstract when you look at the files the instance template actually gives you. These are the surfaces the agent and human owner should use once they move out of the public core repo.

Proof bundle

Definition instance-template/README.md Defines the instance repo as the canonical deployment control plane.
Definition instance-template/START_HERE.md Single-file handoff for agent-driven deployment and operations.
Implementation instance-template/mbr.instance.yaml Canonical desired-state file for domains, host target, release refs, and provider choices.
Implementation instance-template/deploy/README.md Documents deploy assets, host bootstrap, and runtime wiring owned by the instance repo.

`mbr.instance.yaml`

Canonical desired-state file for host target, domains, core release refs, email provider, storage provider, and extension trust configuration.

`agents/bootstrap.md`

Repo-local bootstrap instructions the agent should follow once deployment work moves into the private repo.

`.github/workflows/register-fleet.yml`

Manual registration path for the Move Big Rocks fleet control plane.

`extensions/desired-state.yaml`

Desired extensions for the live installation, separate from core source.

`deploy/`

Host bootstrap assets, service files, and deployment wiring owned by the instance repo.

`security/`

Threat-model and review material for custom extensions and production trust decisions.

Tagged core artifacts

The public package surface is three pinned OCI refs, not a single generic platform image.

The release artifact contract is concrete about what production consumes. Agents should describe the three artifact refs explicitly and point to `mbr.instance.yaml` when explaining where those refs live in desired state.

Proof bundle

Contract docs/RELEASE_ARTIFACT_CONTRACT.md Defines the pinned artifact contract that instance repos consume.
Release platform tags Public tagged core releases that agents can inspect directly.
Build .github/workflows/_build.yml Builds services, migrations, and manifest OCI artifacts and records digests.
Release .github/workflows/production.yml Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
Implementation instance-template/mbr.instance.yaml Shows where pinned release refs live in the private instance control plane.

Core artifact family in desired state

These refs tie public tags, build workflows, and one live installation together.

# mbr.instance.yamlspec:  deployment:    release:      core:        version: v1.1.0        servicesArtifact: ghcr.io/movebigrocks/mbr-services:v1.1.0        migrationsArtifact: ghcr.io/movebigrocks/mbr-migrations:v1.1.0        manifestArtifact: ghcr.io/movebigrocks/mbr-manifest:v1.1.0

Local and owned-runtime path

Local preparation and one-VPS rollout should happen before broader production host work.

Agents can do a lot before touching a broader production host: inspect the public core repo, create the private instance repo, validate `mbr.instance.yaml`, install `mbr` locally, and then either run locally or deploy one owned runtime to prove the workflow shape.

Local setup before host rollout

This sequence keeps evaluation, desired-state validation, and production rollout in the right order.

$ gh repo create acme/mbr-prod --private --template MoveBigRocks/instance-template --clone$ cd mbr-prod$ scripts/read-instance-config.sh mbr.instance.yaml$ curl -fsSL https://movebigrocks.com/install.sh | sh$ sed -n '1,220p' START_HERE.md

Explicit registration

Fleet registration and heartbeat stay explicit.

The self-host story is not "install software that secretly depends on vendor availability." The intended model is explicit registration through the private instance repo when the operator wants support, grandfathering, or future commercial entitlements, plus a coarse weekly heartbeat owned by the host rather than hidden app-runtime code.

Proof bundle

Definition docs/CUSTOMER_INSTANCE_SETUP.md Defines the explicit self-host fleet-registration and disclosed heartbeat model.
Contract docs/AGENT_CLI.md Documents `mbr fleet register` as the explicit registration command.
Implementation instance-template/mbr.instance.yaml Shows the `spec.fleet` block carried by the private instance repo.
Implementation instance-template/deploy/README.md Documents the host-owned registration workflow, fleet config files, and weekly timer.

What the heartbeat is supposed to send

Instance identity, platform version, installed extension slugs and versions, workspace count, and a coarse 30-day activity bucket.

What it should not send

Case content, conversation content, end-user identities, and customer records.

Public disclosure

Privacy notice

Use the public telemetry notice when deployment and trust review become real.

Open resource

Human-supplied inputs

These are the minimum real inputs the agent needs.

The public production guide is already explicit about what a human must still provide. Everything else should move into the repo-driven deployment flow.

Proof bundle

Definition docs/CUSTOMER_INSTANCE_SETUP.md Defines the production self-host setup flow, required inputs, and instance-repo model.
Definition instance-template/README.md Defines the private instance repo as the deployment control plane for one live installation.
Contract docs/RELEASE_ARTIFACT_CONTRACT.md Defines pinned core artifacts and the instance-repo responsibility boundary.
Provenance .github/workflows/production.yml Shows how tests, builds, tags, and artifact digests connect source changes to shipped releases.

One Ubuntu 22.04+ host or VPS.
SSH access to that host.
One domain you control.
One admin email address.
Outbound email provider choice and object storage choice.
GitHub access for the private instance repo.
Production secrets such as `SSH_KEY`, session signing secrets, storage credentials, and extension trust configuration.

Deployment flow

The operational flow is explicit even though the live deploy happens inside the private repo.

The public site should not pretend that production deploys happen from the public core repo. The real flow is public discovery, then private instance repo, then repo-local bootstrap and health verification.

Proof bundle

Contract docs/RELEASE_ARTIFACT_CONTRACT.md Defines the pinned artifact contract that instance repos consume.
Release platform tags Public tagged core releases that agents can inspect directly.
Build .github/workflows/_build.yml Builds services, migrations, and manifest OCI artifacts and records digests.
Release .github/workflows/production.yml Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
Implementation instance-template/mbr.instance.yaml Shows where pinned release refs live in the private instance control plane.

Validate the instance file before deploy

Use the instance-template parser to confirm host, domains, artifact refs, and provider choices before secrets or deploy steps are applied.

$ scripts/read-instance-config.sh mbr.instance.yaml

Release refs stay pinned in desired state

The instance repo should pin core artifact refs instead of rebuilding or retagging core during deploy.

# mbr.instance.yamlspec:  deployment:    release:      core:        version: v1.1.0        servicesArtifact: ghcr.io/movebigrocks/mbr-services:v1.1.0        migrationsArtifact: ghcr.io/movebigrocks/mbr-migrations:v1.1.0        manifestArtifact: ghcr.io/movebigrocks/mbr-manifest:v1.1.0

Verify the live runtime after deploy

Use the CLI health surface after rollout rather than assuming the host state is correct.

$ mbr health check --url https://app.yourdomain.com --json

Upgrading core

Upgrades are a version-pin change, not a rebuild.

Staying current with platform releases follows the same desired-state model as initial deployment. Update the pinned version in `mbr.instance.yaml`, push, and let the deploy workflow handle the blue-green rollout. The instance repo ships with `deploy/UPGRADE.md` as a detailed runbook.

Proof bundle

Contract docs/RELEASE_ARTIFACT_CONTRACT.md Defines the pinned artifact contract that instance repos consume.
Release platform tags Public tagged core releases that agents can inspect directly.
Build .github/workflows/_build.yml Builds services, migrations, and manifest OCI artifacts and records digests.
Release .github/workflows/production.yml Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
Implementation instance-template/mbr.instance.yaml Shows where pinned release refs live in the private instance control plane.

Update the pinned version

Change all four artifact refs to the new tag, commit, and push.

# In mbr.instance.yaml, update spec.deployment.release.core:#   version: v1.2.0#   servicesArtifact: ghcr.io/movebigrocks/mbr-services:v1.2.0#   migrationsArtifact: ghcr.io/movebigrocks/mbr-migrations:v1.2.0#   manifestArtifact: ghcr.io/movebigrocks/mbr-manifest:v1.2.0$ git add mbr.instance.yaml$ git commit -m 'Bump core release to v1.2.0'$ git push origin main

Rollback is the same operation in reverse

Re-pin the previous version and push. The blue-green deploy activates the other slot.

$ git revert HEAD$ git push origin main

Trust review

Production self-hosting still has explicit review gates.

The self-host path is concrete, but it is not supposed to be casual. Extension trust verification, secret handling, access design, and rollout timing remain human-visible decisions.

Keep non-secret deployment state in `mbr.instance.yaml` and sensitive values in GitHub or another secret manager.
Use `EXTENSION_TRUST_REQUIRE_VERIFICATION=true` and related trust settings before installing remote extension bundles in production.
The instance repo is the durable control plane and the host is disposable infrastructure.
Use the preview-workspace and extension review flow before promoting custom extension work into production.

References

Canonical next surfaces.

Each link goes to the next authoritative page, reference, or support surface.

Let agents inspect the CLI-first surface. Let humans decide trust, rollout, and boundaries.

Start from /agents, use /docs/cli as the official product tour, inspect /resources for source and proof, and review /security before making deployment or data-handling decisions.

Open /agents Open resources