Build, package and deploy a project

What happens

03vibe deploy --plan runs the whole default lifecycle in planning mode and prints what each phase would do, ending with the ordered targets of the profile; nothing is written. The real vibe deploy then validates, installs, generates, builds, tests, creates, verifies and packages, skipping every step whose inputs did not change, and applies the packaged artifacts to the profile's targets in order. For every resource it creates it writes a receipt: what was placed where, under which generation, owned by which profile. vibe deployments reads the receipts this machine holds. vibe undeploy --profile local walks the receipts in reverse dependency order and removes exactly what they own, refusing a path that changed after deployment.

04 Deploy profiles select ordered targets; plan is read-only. The engine owns provider selection, collision locks, intent/checkpoints, receipts, three-digest recovery, inverse sequencing and exact resource ownership. vibe-bin plus isolated Claude/Codex/OpenCode skill/plugin adapters implement plan/apply/verify/recover/remove without touching foreign neighbours. Evidence: 0a42456e, 45d88e80, ae36ac48.

By hand

051. Declare what to build, what to deploy and where. A target names an artifact and the mechanism that places it; a profile is an ordered list of targets:

[[artifacts.build]]
id = "build-hello"
mechanism = "build:cargo"
outputs = [{ id = "hello", kind = "executable", select = { package = "hello", bin = "hello" } }]
config = { offline = true }

[[deploy.target]]
id = "local"
artifact = "hello"
mechanism = "deploy:vibe-bin"
config = { command = "hello" }

[deploy]
default_profile = "local"

[deploy.profiles.local]
targets = ["local"]

07The mechanism deploy:vibe-bin places the executable as a launcher in vibe's own bin/ folder on this machine. The command then runs from any terminal; other mechanisms are listed in the specification.

082. Assemble the distributables without touching any destination:

vibe package --path hello-deploy --assume-yes

  → will run `@vibe/package/skill/org.vibevm.world/wal/wal-status` — point=phase:package, handler=builtin:package-skill-project, provider=org.vibevm.world/wal tier=preset
  → package binding [org.vibevm.world/wal]: projected skill `wal-status` (claude=created, codex=created, opencode=created)
lifecycle `package`:
  → validate: ok
  → install: fresh
  → generate: no-op
  → build: no-op
  → test: no-op
  → create: no-op
  → verify: no-op
  → package: ok
  → verification: unavailable (0 input(s), 0 artifact(s))
vibe lifecycle: package completed (8 phases, 1 contribution(s) selected, 1 executed, 1 ok, 0 fresh, 0 notice(s))

103. See the plan for a profile, then deploy it:

vibe deploy --plan --profile local --path hello-deploy

Deploy plan — profile `local` on `windows`
  → local [planned] provider=org.vibevm/vibe#vibe-bin via=the shipped builtin default — artifact `hello` has no record yet, so producing it is planned work
1 of 1 applicable target(s) would be deployed; 0 skipped; nothing was read, built or changed

124. List what this machine holds, and take a profile down:

vibe deployments

no deployments recorded on this machine

14vibe undeploy --profile <name> reverses that profile. The listing never shows secrets.

Artifacts and targets

15The manifest declares what build produces and what package assembles, as artifact targets with dependencies between them. vibe lowers them into one validated graph and records every produced artifact. So package consumes exactly what build verified, and deploy applies exactly what package assembled. An artifact or a target may declare the operating systems it applies to, and a target that does not apply to the current machine is skipped with a note.

16 The strict manifest grammar lowers build/package targets into one dependency-validated artifact DAG. Engine records bind artifact id/kind/path/digest, producer target, logical mechanism, exact provider/version/content, platform and build-affecting input/config/toolchain identity; output existence alone is never freshness. Builtin Cargo selects compiler artifacts only from Cargo JSON messages. Evidence: 2a3f3b44, a22da2a3.

17 Artifact/package and deploy target when.os use the closed windows|linux|macos vocabulary and one injected loading-model OS observation. Global validation remains, then inactive rows project out before provider/source/record/collision/build/load; an active consumer of an inactive producer refuses. Human/JSON output reports deterministic skips and undeploy remains receipt-owned. Evidence: d4edb3ae, 8ff4b711, bb50aeab.

18A deploy profile names its targets in order and the provider that applies each: a folder on this machine, an agent's project or user configuration, and the genres the specification lists. An installed package may replace a built-in provider through an exact pin, so a team can ship its own way of deploying.

19 A real installed package may displace a builtin deploy mechanism through an exact route/pin. The engine reuses ABI-1, R5 prebuilt/source record and immutable-image carriage, admits the generated mechanism manifest and exact operation, and invokes all six deploy operations while retaining plan/receipt/recovery ownership. Restart plan/recovery/undeploy re-resolve once at the command boundary and exact-compare the durable sidecar binding, existing record/image/digest/path without build, repair, publication or builtin fallback. Evidence: 854707a1, 9465291e, 24b1fe4a, 269bec0d, 370ea177, a24e4aff, d475963c.

Edge cases and rules

20Two deploys of the same profile do not race: the engine takes a collision lock per profile and the second waits or refuses, never interleaves.

21A receipt is the only authority for removal. If a file a receipt owns was edited after deployment, undeploy leaves it in place and says so, rather than deleting someone's work.

22--force on a lifecycle verb ignores the recorded fingerprints for one run; it does not change what the run means.

23The deploy phase applies packaged artifacts and nothing else: a step that needs an agent, such as writing release notes, belongs to create, and runs only when the project switches it on.

24 create — the optional agentic producer, our phase Maven does not have. Long, non-deterministic and potentially expensive — therefore LATE (after test: the deterministic baseline is proven before tokens are spent) but before verify/package/deploy. Contributions may use handler = { kind = "agent" }: from a terminal the configured vibe-llm provider executes each explicitly activated contribution as one bounded execution; under an agent host the §6.5 handshake delegates it. An agent handler is a declared workload in its own right, not an LLM enhancement of some hidden algorithmic twin: once activated it fails honestly when neither a provider nor an agent host can execute it, rather than silently disappearing. Provider/config/credential presence activates nothing; omission, host disable or freshness keeps the ordinary chain algorithmic and spends nothing. The phase itself is not a coding agent, planner or repair loop: it executes declared contributions, records/parks their outputs and returns. Skip-when-fresh is vital so an unchanged prompt/spec fingerprint never re-spends tokens (§4.3).