Managed workspaces
How Hypervibe will keep a workspace's repositories, configuration and instructions in one managed desired state, so that a fresh checkout and the workspace's records reproduce it.
On this page
A workspace is the governed container of repositories, lanes and identities that Hypervibe manages for you; it can span several directories and machines. This page covers how its configuration is held, how checkouts stay safe, and how managed files, instructions, drift and recovery work.
A fresh checkout and the workspace's records reproduce its environment #
Hypervibe manages the environment around your code: profiles, agent definitions, skills, tools, connectors, services, secret delivery, builds and recovery. Each setting is a record in the Hypervibe service, the platform's system of record, with an owner, a scope and a revision. A fresh checkout plus the workspace's records is meant to be enough to reproduce that environment, so nobody rebuilds a workspace from someone's home directory.
No configuration file is edited by hand. A tool that must read a file gets a managed projection written for it. Hypervibe adds no configuration folder for each tool and asks you to maintain none. Each machine has one Hypervibe folder, ~/.hyper/. In a repository, the one folder Hypervibe owns is .hyper/: it holds the workspace binding, the id that ties the repository to its workspace, and Hypervibe's own managed files, never a file a person edits. The first release's single-person record, the evidence that a whole run works for one person, requires zero hand edits to Hypervibe configuration after setup.
Each change gets its own checkout, and your work is never reset #
Enrolling a repository records its current commit and fingerprints (digests) of its uncommitted inputs and instructions, and keeps your uncommitted work. Adopting an existing checkout takes an inventory first; it never resets Git, copies a machine's credentials or trusts copied enrollment files.
Each independently reviewable change gets its own writable checkout and Git index; for trusted lanes on one machine, the first design uses a linked Git worktree. Your own checkout is left alone unless you choose it for a change. Two worktrees of one repository keep separate bindings, locks and uncommitted inputs. A managed checkout is reclaimed only once its editors and jobs have released it and its uncommitted files and unpushed commits have a recorded outcome. A closed lane, a merged change or an expired lease never authorizes deletion on its own.
Recipes request, profiles choose and policy decides #
| Record | Holds | Cannot |
|---|---|---|
| Workspace recipe | Source, tools, services, context, agent composition and verification | Grant anything: it only requests capabilities |
| Execution profile | Model and effort, concurrency, resources and acceptance choices | Raise a spending limit or remove a required check |
| Profile layers | A setting's value at default, organization, team, you and this device; the later layer wins | Widen a policy: a preference never does |
| Resolved run manifest | The exact source, recipe, profile, policy, instructions and secret references a run uses | Issue authority |
Policy intersects what the recipe and profile ask for, applies the tightest limits and adds every mandatory check; a contradiction blocks the run. Running work keeps its resolved inputs when defaults change, and grants are rechecked at dispatch.
Hypervibe keeps three states of a workspace apart: desired (the version of the workspace the service has accepted), observed (what each machine reports) and usable (required capabilities pass checks on the installed path). A change the service has admitted is not yet usable.
Every managed file has exactly one mode #
| Mode | What it is | How it changes |
|---|---|---|
| Canonical | Written by people and preserved byte for byte | Changes are proposed as diffs |
| Projection | Generated from registry, profile and instruction records | Edit the source, never the file |
| Observed | Inventoried, not yet adopted | Never written until adopted |
Drift is a projection edited by hand, or a managed file that differs from what Hypervibe recorded. It is shown with both versions and offered as adopt or restore, never silently overwritten. Credentials and Git's own internals are never managed as content.
In the first release, every settings change goes through one write path in the Hypervibe service, and Rocket! and Lanes read the resolved values. Projections, drift handling and adopting existing files follow in later releases. Later releases also pick up a new top-level folder in a repository, adopting a known kind and keeping an unknown kind observed until Fleet decides, and manage repository settings such as CI workflows and required checks.
Instructions compile into context and grant nothing #
Instructions are the documents agents read: AGENTS.md and its scoped files. Every save names the revision it started from, and a stale save opens a conflict showing base, theirs and yours. Hypervibe preserves the text people write and regenerates only managed projections. Rocket! compiles instructions, skills and tool definitions into each agent's context and records where each piece came from; Context and evidence explains the budgets. No instruction can grant a credential or a permission.
Experiments run apart, and recovery never deletes work #
A trial variant of a workspace, used to compare a change before promoting it, gets fresh identities, checkout, grants and budget, and never copies credentials, approvals, live jobs or paid holds. A recorded replay makes no live model call or external effect. Promotion moves a reviewed change, checked against the current base.
Reconciliation keeps authored content that does not overlap, and turns overlap into a recoverable conflict. A missing or truncated desired state never deletes anything; removal needs an explicit removal request that the service has accepted. Rollback is different from pausing, draining or cancelling. A failed migration keeps uncommitted work and unresolved effects.
Where to go next #
- Context and evidence for how context is kept small.
- Work and quality for what happens to a change after it is made.
- Hypervibe platform for profiles, grants and settings.
- Fleet for how unknown folders and machines are decided.