Barista documentation

Barista runs long-lived workloads whose process state can rest without keeping a sandbox active. Start with the current guides below; planned behavior is labelled where it appears.

Use Barista today

• Getting started — run a memory-capable node, create an instance, pause it, and verify that it did not reboot.
• CLI reference — every implemented command, flag, and exit code.
• Examples — direct instances, fleet desired state, scheduled wake, retained snapshots, and scripting.
• Local development — fake versus hypeman, guest binary builds, tests, and macOS limitations.
• Best practices — image, hook, caller, and fleet guidance.

Concepts

• Concepts index
• Sessions
• Sleep and wake
• Snapshots
• Lifecycle and operations
• Capabilities and tiers
• Fleet coordination
• Networking and egress
• Guest agent

Concept pages describe implemented behavior by default. Sections headed Planned explain product direction rather than an available interface.

Reference

• Node Agent API
• Guest Agent API
• Errors and machine-readable reasons

The protobuf packages barista.node.v1alpha1 and barista.guest.v1alpha1 remain the wire-contract source of truth.

Platform

• Architecture — implemented components and the planned gateway boundary.
• Limits and performance — measured resume, pause, snapshot, idle, and cold-boot costs.
• Known issues — current limitations and fallbacks.

Product, decisions, and specifications

These are governance and design inputs, not a getting-started path:

• Business and Requirements Document — binding product vision, requirements, roadmap, and related-work research.
• Phase 1 runtime interface specification — contracts, state machine, and acceptance tests.
• ADR-001 substrate evaluation — evidence for adopting hypeman and deferring the runsc tier.
• ADR-002 coordination evaluation — evidence for bucket leases instead of a control-plane service.
• ADR-003 commercial seam — proposed and awaiting ratification; it has no effect while marked proposed.

Ratified capability requirements live in the repository's OpenSpec specifications.

Evidence and upstream work

• Upstream hypeman findings — measured substrate defects and workarounds still referenced by active work.
• Upstream issue drafts — temporary copies prepared for filing; retain them until filing is confirmed.

Performance evidence consolidated for users is in Limits and performance; Git history retains superseded measurement narratives.