Installation and updates

Use this guide when the first-run installer is not enough. It separates four questions: which distribution surface fits the host, which channel you are on, what the install receipt proves, and how that host can apply an update.

Choose the supported install surface

Claude Code can install through its marketplace. Installable CLI and editor targets use the repository-hosted installer and their rendered package path. App and connector targets receive bootstrap instructions rather than a local package install.

The primary installer line is canonical and must not be rewritten:

curl -fsSL https://guildstack.dev/install.sh | bash

Preview the plan before any write:

curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host claude-code-cli

Installing into more than one detected host requires --yes or interactive consent. A single-host install does not add that multi-host gate. The installer never uses sudo and never edits shell profiles.

Choose stable or beta

Stable follows main and released version tags. Beta follows next, the integration branch where merged work is still being tested.

# stable
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --channel stable

# beta
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --channel beta

For Claude Code, pin the marketplace to beta with:

claude plugin marketplace add lookatitude/guild@next
claude plugin marketplace update guild
claude plugin install guild@guild

Restart the host session after install or update so it can load the new command, skill, agent, hook, and integration surfaces.

Inspect the receipt

Every supported install writes guild.install_receipt.v1 under ~/.guild/receipts/<host>.json, with a copy at the package root. It records the host, channel, ref, commit, and version that were actually installed.

Install evidence

What the receipt can answer

informational Host Which adapter and package path were selected

informational Channel stable, beta, or a deliberately pinned ref

informational Revision The installed commit and version

informational Update path The command the host capability row can honestly support

An install receipt proves what was installed. It does not turn a presentation support label into receipt-verified Public State. Use the host support matrix for that distinction.

Update without overstating automation

The update lifecycle is currently shipped on the beta channel. Session start reads a local cache and may print a one-line update signal; its network refresh runs detached when the cache is stale, so startup does not block on a remote request.

defaults.update.mode accepts:

• notify (default): show the available update and exact command.
• auto: stage an automatic apply only when the selected host capability row says it is implemented.
• off: disable the check.

Automatic apply is currently available only for Claude Code CLI. Wrapper hosts use the operator-invoked guild-run update path. App and connector surfaces are notify-only. All receipted installable hosts can be updated explicitly with:

curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update

Development and symlink installs are excluded from the update signal and apply paths.

Recovery

If the host cannot find the installed command surface after a restart, run /guild:fix where that command exists or repeat the installer with --dry-run for the exact host. Compare the reported plan with the install receipt before rewriting package files.

Where this is defined

• docs/v2/15-distribution.md defines channels, receipts, update checks, and per-host apply capability.
• docs/v2/07-host-adversarial-adaptability.md defines support labels and receipt-derived Public State.
• docs/v2/generated-support-matrix.md records current host evidence.

Continue with Configuration reference to inspect update settings and their source, or Get started with Guild Stack to run the first bounded task.