Power your agent
Yayıncının kendi komutu. PlugMCP uç noktası değildir.
Host a copy with our keys and logs.
npx -y @hypervibe/[email protected]Claude Code'un yerel komutlar için kurulum bağlantısı yok. Aşağıdaki komutu kopyalayın ve bir terminalde çalıştırın.
claude mcp add hypervibe-hypervibe -- npx -y @hypervibe/hypervibe@0.1.43Bir terminalde çalıştırın.
{ "mcpServers": { "hypervibe-hypervibe": { "command": "npx", "args": [ "-y", "@hypervibe/[email protected]" ] } }}claude_desktop_config.json
Uzak URL mi, yoksa makinenizde bir komut mu? İki kurulum arasındaki fark
PlugMCP’de çalıştır
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
BaşlatYayıncıdan
Desired-state infrastructure management from your terminal or agent.
Hypervibe is a desired-state infrastructure orchestrator with two interfaces over one engine: a human/automation-friendly CLI and an for Codex and Claude. Both use the same specs, reviewed plans, provider adapters, connections, receipts, and audit history.
Desired-state infrastructure orchestration through CLI and MCP
You: "Create staging with hosting, Postgres, object storage, a queue, and api.staging.example.com"
Agent: Updates the desired state, plans every provider change and dependency,
applies the reviewed plan, and verifies the resulting services and resources.
Providers and Integrations
Lifecycle maturity is reported by hv_inspect {} and hv_connections {}. Every lifecycle slice below is implemented and ready-for-live; a dated successful live conformance result is still required before any slice is promoted to supported.
Secret Managers
Workloads & Connected Infrastructure
workloadKind: web | worker | cron. Workers are always-on background consumers (on Cloud Run: internal-only ingress, minimum one instance; they must still listen on PORT).queues in the spec declares named message queues: Cloud Run environments get real Pub/Sub topics + subscriptions (apps receive QUEUE_TOPIC_* / QUEUE_SUBSCRIPTION_*); Railway environments are postgres-backed (pg-boss model — requires a declared database; apps consume via DATABASE_URL). Every queue environment gets QUEUE_BACKEND and QUEUE_NAMES.storage declares named private object buckets and an explicit injectInto service list. Ready-for-live providers are Amazon S3 (s3), Azure Blob Storage (azureblob), Google Cloud Storage (gcs), and Railway (railway), independent of the hosting provider. S3/Railway wire the established AWS_* contract; Azure and GCS wire explicit provider-native variables plus OBJECT_STORAGE_PROVIDER and OBJECT_STORAGE_BUCKET. Credentials never appear in specs, bindings, plans, receipts, or logs. Bucket deletion is data-bearing and confirmation-gated.ecs, cloudrun, and azure-container-apps connections are reused automatically for their matching storage provider. Reused GCP access is explicit and staged: hv_connections provider="cloudrun" action="prepare" gcsAccess="inspect" previews read-only inventory access, while gcsAccess="lifecycle" separately previews the broader create/transfer/teardown role. Confirm with adminAuth="default" to use existing Google Application Default Credentials; Hypervibe does not require a second exported token or JSON key. A normal gcloud auth login and Hypervibe's stored deploy service-account key are not user ADC: if ADC is absent, run gcloud auth application-default login and optionally set the quota project before retrying. Hypervibe returns the exact commands, required project roles, official Google setup URL, and retry call without storing the user credential. Otherwise the standalone storage connection accepts the same cloud authentication fields. Region/location is desired state in the spec; Hypervibe creates provider resources and derives workload credentials, so operators do not obtain separate bucket HMAC keys, Azure account keys, or storage-specific settings.cloudrun connection. Cache region/network/subnetwork/tier/size live in hv_spec, and Hypervibe verifies an existing VPC/subnet before configuring Cloud Run Direct VPC egress; it never creates networking implicitly. memorystoreAccess="inspect" stages Redis/Compute read access, while memorystoreAccess="lifecycle" adds the reviewed Redis and network-use roles. Pub/Sub remains independently granted only by queueAccess="lifecycle".gcloud auth application-default login, or Azure's default credential chain (including az login). Explicit credential files remain supported for CI. Expiring local sessions are used for lifecycle and migration only and are never copied into deployed services.cache declares Redis independently from SQL/document databases. Hypervibe wires the cache contract into its consumers; cache deletion is data-bearing and confirmation-gated.us-west-2, an Azure location such as westus2, a GCS location such as us-central1, or a Railway placement such as sjc.Developer Experience
--jsonWith Node.js/npm and your coding agent installed, run one of:
npx -y @hypervibe/hypervibe@latest install codex
npx -y @hypervibe/hypervibe@latest install claude
npx -y @hypervibe/hypervibe@latest install opencode
This installs the shared Hypervibe skill and registers its matching MCP server for your user across projects. Restart your agent after setup. There is no global Hypervibe CLI prerequisite, hosted account, or provider login required for installation. Existing project settings may override your user settings. See agent installation for client versions, configuration preservation, and verification limits. These commands acquire the new integration after the release containing it is published.
The macOS companion includes Codex skill setup through its bundled runtime.
For another existing managed MCP connection, add --skill-only to install the
skill without registering another server.
Download the latest installer from
GitHub Releases.
Choose arm64 for Apple Silicon Macs or x86_64 for Intel Macs. Each DMG has
an adjacent .sha256 checksum file.
Published releases are public on the npm registry. Installation does not require GitHub access, a package token, or custom npm registry configuration.
npm install -g @hypervibe/hypervibe@latest
hypervibe --help
The core desired-state workflow is:
hypervibe spec --file .hypervibe/spec.json
hypervibe plan --env staging
hypervibe apply --plan-id <plan-id>
hypervibe status --env staging
Human-readable output is the default. Add --json for automation, or
--input <file|-> to supply the complete command input as JSON. Confirmation
prompts are TTY-only; scripts must pass explicit confirmation flags.
To connect this exact repository to Hypervibe's hosted reporting without a GitHub PAT:
cd /path/to/your/repository
hypervibe cloud pair
# Open the returned Hypervibe URL and approve the displayed repository.
hypervibe cloud pair --action status
The same workflow is available to MCP clients as hv_cloud_pair: call it once
with action="start", offer to open verificationUrl, then call it with
action="status" after the user approves. Hypervibe detects the GitHub origin,
uses the repositories selected in the Hypervibe GitHub App, and stores the
one-time device and environment credentials only in the encrypted local
connection store. Do not paste a GitHub token or choose an environment.
First-time app setup is prefilled with the checked-out branch. Override it with
--source-branch integration/security (sourceBranch in MCP); a detached
checkout leaves it blank unless supplied. This is only a setup hint: connecting
the app and granting agent access still require separate browser approval.
Pending retries preserve the original hint; choosing another explicit branch
requires finishing the existing approval or waiting for its code to expire.
The same setup hint is available for cloud requests --action authorize and
cloud connections --action start. Deploy the compatible Hypercloud server
and migration before updating clients; see compatibility and evidence.
For credentials supplied by someone else through Hypervibe, use the separate one-time secret import:
hypervibe cloud secrets --request-id <request-uuid> --env staging
# Approve the displayed comparison code in the browser, then:
hypervibe cloud secrets --action receive --request-id <request-uuid> --env staging --confirm
This requires the companion hosted retrieval feature and an engine release
containing this command. Reporting pairing alone does not grant secret access.
The import fills the private .env.staging, never .env.example, and returns
references for a fresh reviewed plan. It does not deploy.
To run the current source checkout instead:
git clone https://github.com/davejohnson/hypervibe.git
cd hypervibe
npm ci
npm run build
node dist/index.js --help
After restarting your configured agent:
You: "Show me which provider connections this staging spec requires"
Claude: Lists the hosting, database, storage, queue, DNS, and integration connections needed by the plan.
You: "Connect those providers using my local credential references"
Claude: Validates each reference locally and stores the verified connections securely.
For a first GCP deploy, Hypervibe can create or reuse the project, link the billing account you explicitly choose, create the repository-scoped deploy identity, prepare Cloud Run and Cloud SQL, and save both verified connections. It uses your current Google Application Default Credentials only for setup; you never copy a generated key:
hypervibe connections --provider cloudrun --action bootstrap \
--project my-app --admin-auth default
# Use target.projectId from the preview and approve one exact billing account:
hypervibe connections --provider cloudrun --action bootstrap \
--project my-app --gcp-project-id PROJECT_ID_FROM_PREVIEW --admin-auth default \
--billing-account-name billingAccounts/AAAAAA-BBBBBB-CCCCCC --confirm
The read-only preview chooses a stable project name or reuses verified access
for this repository. Pass --gcp-project-id to preserve an explicit choice.
The confirmed call can create a project, link
billing, and create credentials, so Hypervibe always stops for the exact
billing-account choice first. Staging and production remain separate
desired-state environments; deploy staging first and promote its verified
release to production explicitly.
You: "Create a new project called my-app with staging and production environments"
You: "Add the API, worker, Postgres, documents bucket, and events queue to staging"
You: "Attach api.myapp.com and manage its DNS"
You: "Plan and apply staging"
You: "Verify the services and connected resources"
Environment custom domains use the same spec/plan/apply loop for Cloud Run,
DigitalOcean App Platform, Railway, and Vercel.
Hypervibe attaches the hostname at the provider first, writes only returned
Cloudflare records, persists exact provider/DNS ids, and confirmation-gates
exact detach. Cloud Run stays DNS-only during its native certificate flow.
GitHub Pages custom domains use the separate project-level github.pages
lifecycle.
Let Hypervibe create opaque application secrets whenever the app does not need a value issued by somebody else. A declared Hypervibe-owned session secret is generated, encrypted into the plan, and installed during apply without asking the user to invent or copy a value.
For credentials issued by another system or owned by another person, declare a delegated slot and supply a local or secret-manager reference when planning:
You: "Connect to Vault at https://vault.mycompany.com"
You: "Plan production with APP_SIGNING_KEY from vault://secret/myapp/runtime#signing-key"
Claude: Resolves the value locally, encrypts it into the reviewed plan, and injects it only during hv_apply.
Secret references use the format: provider://path[#key][@version]
Provider access can also be shared privately with the hosted app through
hv_cloud_connections / hypervibe cloud connections: start and status
approve this device, preview shows exact destinations, and connect requires
that previewId plus confirm=true. Use a verified saved connection or a
private credentialsRef; deployment credentials are reused only when their
credential role matches monitoring. Existing hosted connections are preserved.
revoke removes this device's upload access. Reporting pairing remains separate.
┌───────────────┐
│ Hypervibe CLI │
└───────┬───────┘
│
┌───────────────┐ ▼
│ MCP clients ├──► Command registry/context/results
└───────────────┘ │
▼
Spec → Plan → Apply → Status
│
▼
Provider and secret adapters
Hypervibe exposes the same focused operations as canonical hv_* MCP tools and friendly CLI commands. The core is a Terraform-style loop:
hv_spec — declare the desired state (services, database, cache, storage, load balancer, domain, email, messaging, env vars) as a revisioned spechv_plan — observe live infrastructure, diff against the spec, and get an executable planhv_apply planId=... — converge. Stale plans are rejected; destroying data-bearing resources requires explicit confirmationhv_status — see drift between desired and observed state at any timeAround that core: hosted reporting pairing (hv_cloud_pair), provider
connections (hv_connections), deploy/rollback, logs/errors/health, bounded
database diagnostics, secrets, domains/DNS, email, payments, CI, App
Store/TestFlight, and local dev tools.
hv_connections and hv_secrets both accept project="name-or-id" to select and validate project context. Provider scope remains separate: it identifies the actual repository, domain, account, or environment covered by a credential.
Their parameter modes are intentionally explicit:
hv_connections # list globally
hv_connections project="my-app" # list; validate project context
hv_connections project="my-app" provider="github" credentialsRef="env:NODE_AUTH_TOKEN"
hv_secrets # list sources globally
hv_secrets project="my-app" # list sources; validate project context
hv_secrets project="my-app" env="staging" # masked hosting-variable names
hv_inspect # provider/capability discovery; no parameters
hv_inspect provider="cloudrun" # connection verification; discovery advertises each resource selector contract
hv_inspect provider="cloudrun" project="my-app" env="staging" region="us-central1" # full live environment
hv_inspect provider="cloudsql" resource="database" limit=25 # bounded Cloud SQL instance inventory
# Recover an abandoned host from a migration that predates retained bindings.
hv_inspect provider="cloudrun" project="my-app" env="production" region="us-central1"
hv_import provider="cloudrun" mode="retained-cleanup" project="my-app" env="production" region="us-central1" confirm=true
hv_import provider="cloudsql" mode="retained-database-cleanup" project="my-app" env="production" id="exact-instance-id" confirm=true
hv_import provider="memorystore" mode="retained-cache-cleanup" project="my-app" env="production" id="exact-cache-id" confirm=true
# Discover and safely remove billable remnants left after their owning runtime was deleted.
hv_inspect provider="cloudsql" project="my-app" resource="backup" limit=25
hv_import provider="cloudsql" mode="retained-resource-cleanup" resource="backup" project="my-app" env="production" id="projects/gcp-project/backups/exact-backup-id" confirm=true
hv_inspect provider="cloudrun" project="my-app" resource="artifact" limit=25 # all Artifact Registry locations
hv_import provider="cloudrun" mode="retained-resource-cleanup" resource="artifact" project="my-app" env="production" id="projects/gcp-project/locations/us-central1/repositories/exact-repository" confirm=true
hv_plan project="my-app" env="production" scope="retained-cleanup" # review exact confirm-gated cleanup actions
For hv_inspect, any bounded selector requires provider; project plus env never replaces it. Parameterless discovery reports every resource mode's selector contract and whether it accepts limit. Every database, cache, and storage lifecycle provider is required at registration time to expose bounded exact-id/name inventory with durable provider scope. Selecting a non-current hosting provider runs read-only provider-scoped environment forensics and never passes the current provider's binding to that adapter. The retained cleanup import modes only record complete inspected identities locally; they do not delete anything until a later isolated plan is explicitly confirmed. For hosting-variable mode, hv_secrets requires an explicit env and does not infer staging from project alone.
docs/TOOLS.mdnpm run build && npm run docs:toolshv_db_query can diagnose managed Postgres without asking you to expose it permanently. Railway uses a temporary TCP proxy, Cloud SQL uses a local authenticated connector, and an ECS-hosted RDS instance gets a separately labelled temporary /32 security-group rule for the Hypervibe caller in addition to its workload-group-only runtime rule. Supabase normally uses its existing direct endpoint, so no temporary provider resource is needed. Hypervibe releases only access it created; concurrent queries share the same short-lived lease, and every response reports the access mode and cleanup status without returning database credentials or endpoints.
Diagnostic reads run in a PostgreSQL read-only transaction with a 30-second statement timeout. Results are capped at 500 rows and 512 KiB. Mutations still require allowMutations=true, and multi-statement SQL remains blocked.
PostgreSQL services receive the canonical managed variables DATABASE_URL and
DIRECT_URL. Applications with a legacy name can declare a per-service alias;
Hypervibe resolves it inside plan/apply and never writes the database value to
the spec:
{
"services": {
"events-worker": {
"workloadKind": "worker",
"startCommand": "npm run events:worker",
"public": false,
"databaseEnvAliases": {
"POSTGRES_DB_URL": "DATABASE_URL"
}
}
},
"database": {
"provider": "rds",
"engine": "postgres"
}
}
hv_plan and hv_status expose the key-only contract and verify that each
declared alias is attached to its target service. inSync describes
configuration convergence; runtimeHealth remains unverified until HTTP
health or worker log/error evidence is checked.
Email sender identity, inbound parsing, delivery events, and mailbox forwarding belong in the environment spec. One environment may declare one default sender, one SendGrid Inbound Parse route, and the account-level delivery-event webhook:
{
"domain": "example.com",
"services": {
"api": { "workloadKind": "web", "public": true }
},
"email": {
"enabled": true,
"sender": {
"address": "[email protected]",
"name": "Example",
"replyTo": "[email protected]"
},
"inbound": {
"hostname": "inbound.example.com",
"service": "api",
"path": "/webhooks/sendgrid/inbound",
"aliases": ["support", "replies"],
"spamCheck": true,
"sendRaw": false
},
"deliveryEvents": {
"service": "api",
"path": "/webhooks/sendgrid/events",
"events": ["processed", "delivered", "bounce", "dropped"]
},
"forwarding": {
"aliases": {
"support": "[email protected]",
"billing": "[email protected]"
},
"catchAll": { "action": "drop" }
}
}
}
hv_plan separates runtime-key projection, SendGrid sender/domain
authorization, Cloudflare DNS, inbound-parse creation, delivery events,
forwarding destination verification, aliases, catch-all routing, and domain
validation into reviewable actions. hv_apply installs SENDGRID_API_KEY plus the
declared sender defaults on each service; the inbound target also receives
SENDGRID_INBOUND_HOSTNAME and a JSON SENDGRID_INBOUND_ALIASES value.
SendGrid routes inbound parsing by hostname, not local-part alias. The target
service reads the recipient from the parsed request and dispatches aliases such
as [email protected] itself. Domain authentication authorizes sender
addresses under domain; without a domain, a declared sender uses SendGrid's
single-sender verification flow and apply remains pending until its verification
email is accepted. Cloudflare destination creation returns pending until the
destination mailbox accepts its verification email; forwarding rules run only
afterward. Because SendGrid exposes one delivery-event webhook per account, the
project spec may declare deliveryEvents in only one environment.
A staging application can use the same inbound-email lifecycle as a CI test
inbox without a separate mailbox service. Give the CI traffic its own inbound
hostname and leave aliases empty because per-run recipient local parts are
temporary application state, not durable provider configuration:
{
"domain": "staging.example.com",
"services": {
"api": { "workloadKind": "web", "public": true }
},
"email": {
"enabled": true,
"sender": {
"address": "[email protected]",
"name": "Example Canary"
},
"inbound": {
"hostname": "ci-mail.staging.example.com",
"service": "api",
"path": "/api/webhooks/canary-email-receipts",
"aliases": [],
"spamCheck": true,
"sendRaw": false
}
}
}
Hypervibe owns the SendGrid authorization and Inbound Parse route, Cloudflare MX record, and hosting runtime projection. The application owns the test-inbox behavior: it can issue a short-lived recipient from a protected endpoint or let CI derive one from an application canary secret, the webhook accepts only valid recipients and stores the minimum verification result, and a protected polling endpoint returns that result to CI. The CI job may need that application canary credential and the non-secret inbound hostname, but it never needs the SendGrid API key.
An unguessable recipient is staging isolation, not proof that SendGrid sent the
request. Apply strict request-size limits, short recipient expiry, and
capability-aware rate limits rather than one small shared provider-IP bucket.
SendGrid stops retrying only after a 2xx response, so permanently invalid or
over-limit payloads should be acknowledged and discarded; reserve 5xx for
transient failures that can succeed on retry.
Applications that require provider-origin authentication must verify SendGrid's
signed multipart request without changing its raw bytes, or put SendGrid OAuth
in front of the webhook. Signature keys, OAuth tokens, message storage, and
receipt APIs remain application-owned; Hypervibe does not currently provision
or rotate those credentials.
Twilio support deliberately covers the shared setup most applications need: a Messaging Service, optional inbound-message and delivery-status callbacks, the runtime credentials, and optional attachment of an existing phone number.
Collect these values from the same Twilio account or subaccount:
Do not look for an MG... SID before setup. The spec declares a friendly
service.name; Hypervibe creates or explicitly adopts that Messaging Service,
records its MG... SID, and projects TWILIO_MESSAGING_SERVICE_SID during
apply.
{
"services": {
"api": { "workloadKind": "web", "public": true }
},
"messaging": {
"provider": "twilio",
"services": ["api"],
"service": {
"name": "example-production",
"inbound": {
"service": "api",
"path": "/webhooks/twilio/messages"
},
"deliveryStatus": {
"service": "api",
"path": "/webhooks/twilio/status"
}
},
"sender": {
"phoneNumberSid": "PN0123456789abcdef0123456789abcdef"
}
}
}
Create a Restricted API key with these exact Twilio permissions:
twilio/messaging/services/list
twilio/messaging/services/read
twilio/messaging/services/create
twilio/messaging/services/update
twilio/messaging/services.phonenumbers/list
twilio/messaging/services.phonenumbers/create
twilio/messaging/services.phonenumbers/delete
twilio/messaging/messages/create
Keep the four connection values in a local, gitignored env file:
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY_SID=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY_SECRET=replace-with-the-one-time-secret
TWILIO_AUTH_TOKEN=replace-with-the-primary-auth-token
Connect that file by reference:
hv_connections provider="twilio" credentialsRef="dotenv:/absolute/path/.env" credentialsMap={"accountSid":"TWILIO_ACCOUNT_SID","apiKeySid":"TWILIO_API_KEY_SID","apiKeySecret":"TWILIO_API_KEY_SECRET","authToken":"TWILIO_AUTH_TOKEN"}
hv_plan reviews Messaging Service creation/adoption, sender attachment, and
runtime projection separately. hv_apply derives webhook URLs from the target
service's public binding and projects the Twilio values only to
messaging.services. Moving a number from another sender pool requires exact
action confirmation. Hypervibe does not buy numbers or manage Voice, Verify,
WhatsApp, A2P registration, campaigns, or application message sending.
Complete any A2P 10DLC, toll-free verification, or other regulatory setup in
Twilio before production sending. The primary Auth Token is still required even
when API calls use a restricted key because Twilio uses the account token to
sign inbound and delivery-status webhooks.
Hypervibe treats infrastructure as a repo-backed definition, not as one user's private local state. When run from a git worktree, hv_spec writes the desired infrastructure shape to:
.hypervibe/spec.json
Commit that file with the app. It is the shared source of truth for environments, services, cron jobs, databases, caches, delegated secret ownership, domains, email, messaging, env vars, deploy strategy, and migrations. When a teammate clones the repo and runs hv_spec, hv_plan, or hv_status, Hypervibe reads this file, creates a local project cache if needed, and reports any missing provider connections before apply. The local project_specs table is a revision journal behind this file: if spec.json is edited outside Hypervibe (or pulled with new changes), the next read adopts it as a new revision and says so in a warning.
Hypervibe also maintains non-secret provider identity bindings in:
.hypervibe/bindings.json
This file lets teammates observe and converge the same provider resources instead of planning duplicate projects/services. It is for non-secret IDs such as provider project IDs, environment IDs, service IDs, custom domain bindings, and CI workflow sync metadata. Credentials, tokens, passwords, database URLs, and secret values stay out of the repo and remain local/provider-side.
No Hypervibe user role is required. The current chat task determines which access is needed:
When a collaborator lacks that connection, Hypervibe should offer two paths: connect credentials they already control, or prepare a value-free handoff naming the provider, scope, environment, and blocked task for the infrastructure owner. It should not assume that every coder belongs in each hosting, data, DNS, or integration provider account. This stays local and repo-backed; it does not require a new Hypervibe web service or shared drift database.
Use a Hypervibe-owned slot for opaque runtime values the application needs but the user should never have to choose, see, or paste:
{
"secrets": {
"SESSION_SECRET": {
"ownership": "hypervibe",
"generator": "random-base64url-32-v1",
"generation": 1,
"environments": ["production"]
}
}
}
hv_plan derives a cryptographically strong value scoped to the project,
environment, key, generator, and generation. It freezes that value only inside
the encrypted plan; hv_apply installs it in every service and records only a
hash plus generator provenance. The value never appears in the spec, local env
templates, previews, status, logs, or receipts. Replanning on the same Hypervibe
installation produces the same value, including after a partial provider
failure, so a retry cannot split services across different session secrets.
Increment generation only for an intentional rotation. Replacing a live
secret is confirmation-gated because it can sign users out or invalidate other
application state. Back up Hypervibe's .secret-key (or keep a stable
HYPERVIBE_SECRET_KEY in a hosted installation): Hypervibe blocks rather than
silently rotating if it cannot reproduce an accepted generated value.
Use a delegated secret slot when a collaborator, customer, or app owner should supply and rotate a runtime or GitHub Actions credential without giving it to the repository owner. The spec records the name, responsible principal, and provider destinations, but never the value:
{
"secrets": {
"ANTHROPIC_API_KEY": {
"ownership": "delegated",
"principal": "github:alice",
"environments": ["production"],
"githubActions": { "repository": true },
"required": true,
"driftPolicy": "preserve"
}
}
}
The principal is a non-secret ownership label, not an authenticated Hypervibe
identity. Provider credentials remain the enforcement boundary, but Alice does
not need provider membership merely to own the API key. She can send the key
to the infrastructure owner through an agreed out-of-band channel; the owner
stores it in a local safe reference such as 1Password, a private env file, or
another supported manager and runs the plan/apply. A shared secret-manager
item is the natural repeatable handoff when both people already use one. Give
Alice narrowly scoped provider membership and have her connect her own
credentials only if she needs to apply independently. Changing principal or
a collaborator list in a checkout does not grant a provider role. Without a
hosted control plane, Hypervibe cannot prove that the person supplying a key is
github:alice; do not auto-apply unreviewed spec changes with an owner/admin
credential.
For Anthropic, Alice creates a standard workspace-scoped API key at Claude Platform API keys. Claude subscription billing and Claude API billing are separate, so the Platform account/workspace must have API billing configured. She saves the value locally, outside the repository:
# /Users/alice/.config/hypervibe/friend-app.env
ANTHROPIC_API_KEY=...
If Alice will apply independently, she connects only the provider credentials
she already controls. hv_plan reports the exact credential type, official
setup URL, permissions, and resource scope for every required connection; she
stores each value outside the repository and passes only a safe local
reference:
hv_connections provider="<required-provider>" credentialsRef="dotenv:/Users/alice/.config/hypervibe/provider.env#PROVIDER_TOKEN"
Then she creates and applies a plan without sending either token through chat:
hv_plan project="friend-app" env="production" secretRefs={"ANTHROPIC_API_KEY":"dotenv:/Users/alice/.config/hypervibe/friend-app.env#ANTHROPIC_API_KEY"}
hv_apply project="friend-app" planId="<planId>"
The value is resolved on Alice's machine, encrypted into that specific plan, injected into every service in the target environment, and never returned by a tool. Hypervibe records only the principal, a SHA-256 value hash, timestamp, and apply receipt in local SQLite. That verifier is deliberately omitted from .hypervibe/bindings.json, where a low-entropy delegated value could otherwise be brute-forced offline. Ordinary envVars and .env loading cannot overwrite a delegated key. Missing values, out-of-band drift, or a changed principal produce an inspectable but non-executable plan that preserves the live value until a new explicit secretRefs input is supplied.
If a machine or local Hypervibe database is lost, recloning the committed .hypervibe/spec.json and .hypervibe/bindings.json restores the desired shape and non-secret provider identities. Accepted managed-secret hashes, provider connections, and in-flight plans must be recreated locally; no runtime secret value or verifier is recoverable from the repo.
.envFor every declared target, hv_plan prepares a private, gitignored .env.<environment> file even when env-file loading is disabled. When loading is enabled, the target file wins over repo .env; existing target values are preserved, and newly eligible base values are appended. Hypervibe does not blindly copy or publish every key. The default policy is envFile.mode: "runtime": Hypervibe syncs high-confidence app runtime keys such as SENDGRID_API_KEY, SESSION_SECRET, *_URL, *_TOKEN, *_SECRET, APP_*, VITE_*, and similar names; it treats blank assignments as missing; it skips delegated secrets, generated or infrastructure-managed values, provider/control-plane credentials such as HYPERVIBE_*, RAILWAY_API_TOKEN, GITHUB_TOKEN, and CLOUDFLARE_API_TOKEN; it skips local-looking runtime values such as localhost, 127.0.0.1, 0.0.0.0, host.docker.internal, .local, and .internal; and it reports affected key names in the plan. envFile.mode: "off" or includeEnvFile: false leaves the target scaffold in place but copies no ordinary base values.
When a spec is written from its matching checkout, Hypervibe non-destructively prepares both .env and .env.example with the exact delegated-secret and envFile.include names declared by that project—for example, RECAPTCHA_V3_SITE_KEY= and RECAPTCHA_V3_SECRET_KEY=. Hypervibe-owned generated secrets are deliberately omitted because there is nothing for the user to fill in. Every input slot gets a short comment; existing values, owner comments, and ordering are preserved, while stale Hypervibe-owned comments are refreshed. The tracked .env.example stays value-free and points people to the private file. Actual missing connections add only their provider-declared local inputs, such as HYPERVIBE_RAILWAY_TOKEN, rather than every credential Hypervibe supports. Hypervibe first proves each exact private path is a regular, untracked, repository-ignored file (adding root rules such as /.env or /.env.production, plus !/.env.example only when needed), refuses symlinks and tracked secret files, creates new private env files with mode 0600, and removes group/world access from an existing private file without adding owner permissions. The receipt reports when permissions changed.
Tune this per environment in .hypervibe/spec.json:
{
"envFile": {
"mode": "explicit",
"include": ["SENDGRID_API_KEY", "CUSTOM_WORKER_FLAG"],
"exclude": ["LOCAL_DEBUG_FLAG"]
}
}
Modes are runtime (default), all, explicit, and off. Values loaded from the env file are encrypted into the plan and never printed. The plan warning names the env file path and selected keys so the agent can show the user exactly what source is being applied. Generated infrastructure values such as DATABASE_URL still win over stale local .env values.
Use a separate scoped Stripe connection for each named Stripe sandbox and for production. The connection scope is the stable mapping between a Hypervibe environment and Stripe; it defaults to the Hypervibe environment name.
For an existing Stripe dotenv file:
hv_connections provider="stripe" scope="staging" credentialsRef="dotenv:/absolute/path/.env.stripe-sync.staging" credentialsMap={"secretKey":"STRIPE_SECRET_KEY"}
If the file also contains a publishable key:
hv_connections provider="stripe" scope="staging" credentialsRef="dotenv:/absolute/path/.env.stripe-sync.staging" credentialsMap={"secretKey":"STRIPE_SECRET_KEY","publishableKey":"STRIPE_PUBLISHABLE_KEY"}
Repeat with scope="development" for a development sandbox and
scope="production" for Stripe live mode. Sandbox keys begin with sk_test_
or rk_test_ and pk_test_; production server keys begin with sk_live_ or
rk_live_. Restricted rk_ keys are preferred and are accepted in the
secretKey connection field. Open the intended sandbox before revealing its
API keys because each Stripe sandbox has its own isolated key pair and objects.
See Stripe sandbox management
and sandbox API-key access.
Stripe sandbox creation itself is a short Dashboard step because an ordinary sandbox API key cannot create another sandbox or its keys. Everything after that stays in Hypervibe's desired-state loop:
In Stripe's account picker choose Switch to sandbox → Create sandbox.
Name it for the project or workflow and open it. Copy a restricted rk_test_
key (or an unrestricted sk_test_ key) and the optional pk_test_ key into
a gitignored .env.stripe.development.
Connect that exact sandbox:
hv_connections provider="stripe" scope="development" credentialsRef="dotenv:/absolute/path/.env.stripe.development" credentialsMap={"secretKey":"STRIPE_SECRET_KEY","publishableKey":"STRIPE_PUBLISHABLE_KEY"}
Declare payments.stripe.environment: "development", catalog prices,
runtime credential projection, and webhooks; run hv_plan and hv_apply,
then verify the managed CI release with hv_ci_status and hv_health.
In the following desired-state revision, add a versioned application seed
such as npm run db:seed:personas -- --dataset=invoice-perfect-v1. The seed
owns paired application rows and Stripe test customers/subscriptions;
Hypervibe owns only their prerequisites and execution receipt.
For a clean reset, create another named sandbox, replace the two local dotenv
values, and run the same scoped hv_connections call. hv_plan then reviews
recreation of products, prices, environment projection, and webhooks against
the empty target. The old sandbox is untouched and can be deleted in Stripe
after the replacement and fixtures are verified.
Application seeds must use stored provider IDs and deterministic Stripe metadata as durable fixture identity. Stripe idempotency keys protect immediate retries but expire; they do not replace reconciliation. Keep baseline personas stable. Add test-clock personas later as disposable fixtures because deleting a test clock also deletes its associated Stripe test objects.
Then declare the Stripe catalog Hypervibe owns and which hosting services
receive its runtime values. Products and recurring prices are lifecycle
resources: hv_plan observes them, proposes explicit create/update/adopt/
replace/archive actions, and hv_apply records durable provider IDs:
{
"payments": {
"stripe": {
"environment": "staging",
"services": ["web", "cron"],
"credentials": {
"secretKeyEnvVar": "STRIPE_SECRET_KEY",
"publishableKeyEnvVar": "STRIPE_PUBLISHABLE_KEY"
},
"catalog": {
"products": {
"starter": {
"name": "Starter",
"description": "Starter subscription",
"prices": {
"monthly": {
"unitAmount": 1900,
"currency": "usd",
"interval": "month",
"envVar": "STRIPE_STARTER_MONTHLY_PRICE_ID"
},
"yearly": {
"unitAmount": 19000,
"currency": "usd",
"interval": "year",
"envVar": "STRIPE_STARTER_YEARLY_PRICE_ID"
}
}
},
"pro": {
"name": "Pro",
"prices": {
"monthly": {
"unitAmount": 4900,
"currency": "usd",
"interval": "month",
"envVar": "STRIPE_PRO_MONTHLY_PRICE_ID"
}
}
}
}
}
}
}
}
Unbound products and prices with exactly matching identity/configuration are offered as confirm-gated adoption actions. Multiple candidates block rather than choosing one. Recurring price amount, currency, and interval are immutable in Stripe; changing one creates a replacement, updates hosting variables, and only then offers a confirm-gated archive of the previous price. Removing a managed price or product likewise removes its hosting projection before archiving it. Unmanaged Stripe objects are untouched.
hv_plan reads Stripe and hosting state, but persists only provider identities,
managed key names, and hashes—not credentials or webhook signing values.
hv_apply resolves the encrypted Stripe connection again and writes runtime
values through the hosting adapter. With CI-triggered branch deploys, the
adapter preserves the approved exact-SHA workflow as the next code-release
boundary instead of turning a configuration sync into an unrelated source
release. Stripe-managed keys
cannot also be supplied through envVars, .env includes, delegated secrets,
one-off overrides, or removeEnvVars.
Declare webhook endpoints in the same desired-state section instead of calling an imperative setup command:
{
"payments": {
"stripe": {
"environment": "staging",
"webhooks": {
"billing": {
"url": "https://billing.example.com/api/webhooks/stripe",
"service": "web",
"envVar": "STRIPE_WEBHOOK_SECRET",
"events": [
"checkout.session.completed",
"customer.subscription.updated",
"customer.subscription.deleted",
"invoice.paid",
"invoice.payment_failed"
]
}
}
}
}
}
envVar defaults to STRIPE_WEBHOOK_SECRET, and events defaults to the
common SaaS event set when omitted. hv_plan observes endpoint identity and
hosting value hashes. A single existing endpoint with the declared URL and an
observed hosting value becomes an explicit confirm-gated adoption action;
multiple matches are blocked. Creation syncs Stripe's creation-only signing
value to the named service and stores only the endpoint id plus a one-way hash.
Replacement/rotation and deletion are also confirm-gated. If hosting sync
fails, apply rolls the new endpoint back and verifies its absence; an
unverifiable rollback records the endpoint id so a later plan cannot create a
duplicate.
Keep App Store identity, capabilities, TestFlight groups, and the release workflow in each environment's desired state. The server and iOS code may live in the same repository (the v1 workflow is monorepo-first), while release evidence records mobile and server repository/SHA fields separately:
{
"hosting": { "provider": "cloudrun" },
"services": { "api": {} },
"deploy": {
"strategy": "branch",
"trigger": "ci",
"branch": "main"
},
"ios": {
"bundleId": "com.example.app",
"capabilities": ["PUSH_NOTIFICATIONS"],
"testflight": {
"groups": {
"Internal": {
"internal": true,
"testers": ["[email protected]"]
}
}
},
"release": {
"services": ["api"],
"trigger": "after-server-deploy",
"build": {
"workingDirectory": "apps/ios",
"command": "bundle exec fastlane build",
"ipaPath": "build/Example.ipa",
"requiredSecrets": ["SENTRY_AUTH_TOKEN"]
},
"signing": {
"provider": "match",
"gitBranch": "main"
},
"testflight": {
"groups": ["Internal"],
"usesNonExemptEncryption": false,
"submitForBetaReview": false
}
}
}
}
hv_plan/hv_apply reconcile the bundle ID, capabilities, beta groups,
server deploy workflow, iOS release workflow, and its App Store Connect
environment secrets. With signing.provider: "match", the matching GitHub
environment must already contain MATCH_GIT_URL, MATCH_PASSWORD, and
MATCH_GIT_BASIC_AUTHORIZATION. Hypervibe observes those names and scopes the
values to read-only signing preparation; they never enter Hypervibe state or
the project build step. build.requiredSecrets is only for additional secrets
needed by the app-defined build command.
The server workflow uploads release evidence only after provider deploy success. The iOS workflow uses a separate app queue and checks changes before protected jobs or approvals. It verifies the exact deployed source and builds only when mobile inputs changed or relevance cannot be proven. Evidence artifacts use a versioned namespace; after an evidence-contract upgrade, an ordinary server release refreshes evidence for iOS releases and unprotected rollback. API-protected environments require a reviewed baseline migration when API evidence is missing, and currently block rollback. Its build job checks out that exact commit, installs existing Match assets into an ephemeral keychain, runs the project build, validates the IPA, and uploads a short-lived artifact. A fresh release job revalidates the artifact and server evidence before running Hypervibe's embedded Apple upload, processing, compliance, declared-group distribution, optional beta-review, and release-manifest runtime. App Store credentials never enter the project build job, and the release job never checks out or executes project code.
Use signing.provider: "project" when a project intentionally owns its signing
implementation. Versioned App Store metadata/screenshots and local device builds
remain project files; neither becomes an imperative Hypervibe command.
The iOS artifact records separate mobile and server provenance. Inspect these
workflows through hv_ci_status; final hv_appstore_submit also refuses
submission until the exact tested Apple build and current target server release
are verified, then requires confirmation. Declare ios.release.promoteFrom to
promote a tested beta without rebuilding it. Cross-commit reuse requires verified
API evidence for the unchanged supported contract.
Declare versioned API contracts and application compatibility tests to protect old web/mobile clients during server releases. New versions coexist with old ones; retirement requires an explicit confirmed policy change. See API compatibility and iOS releases for setup, workflow behavior, and evidence limits.
Omitting a key from envVars, an env file, or a local secret input means
preserve the provider value. Hypervibe never treats a partial desired map
as permission to delete live variables.
Delete a retired key only through the environment's explicit tombstone list:
{
"envVars": {
"NEW_FEATURE_FLAG": "enabled"
},
"removeEnvVars": ["OLD_FEATURE_FLAG"]
}
hv_plan emits one service:<name>:env-remove action per affected service.
The action shows key names but no values, and hv_apply skips it unless that
exact action ID is passed in confirmActions. GCP Cloud Run and Railway both
support these explicit removals. Hypervibe-managed database, queue, storage,
delegated-secret, and source-integration keys cannot be tombstoned; change or
remove the owning resource instead.
Renames require two releases:
removeEnvVars. Review and explicitly confirm the removal action.Hypervibe rejects a removal plan while any service configuration is still
drifting. This prevents a same-release SOME_TOKEN to ANOTHER_TOKEN change
from removing the old value before compatible code is running. A confirmed
removal may reconcile or redeploy the provider's already-compatible current
image, so do not collapse these two releases into one.
To promote real data from one environment into another, declare a one-use
dataMigration on the target rather than renaming environments or running a
provider CLI:
{
"dataMigration": {
"id": "initial-production-launch",
"fromEnvironment": "staging",
"include": { "database": true, "storage": ["documents"] }
}
}
Hypervibe isolates the confirmed copy stage, restores into fresh unreachable targets, verifies non-secret database/storage manifests, and records the new bindings only after success. Re-run plan/apply to cut services over, verify the production release, then re-plan to review deletion of retained rollback targets. See the full migration workflow.
The copy is authorized only while both source and target declare
"maintenance": { "enabled": true } and Hypervibe freshly verifies the full
boundary: a Cloudflare-owned static 503 marker, every hosting workload stopped,
and PostgreSQL defaulting new sessions to read-only. Azure Container Apps, GCP
Cloud Run, DigitalOcean App Platform, Railway, and Vercel implement reversible
workload maintenance. AWS ECS Express currently fails closed before the copy.
DigitalOcean's exact-app archive/restore path and Vercel's exact-ID pause/unpause
path are implemented and remain behind their opt-in live maintenance promotion
gates.
No application maintenance flag, email dry-run switch, or AI dry-run switch is
introduced.
Cloud SQL can manage regional availability, backup/PITR retention, named read replicas, and a scheduled isolated restore drill through normal desired state:
{
"github": { "canonicalEnvironment": "production" },
"environments": {
"production": {
"hosting": { "provider": "cloudrun" },
"services": { "web": {} },
"database": {
"provider": "cloudsql",
"resilience": {
"availability": "regional",
"backups": { "retainedBackups": 8, "pitrRetentionDays": 7 },
"replicas": { "analytics": { "region": "us-west1" } },
"restoreDrill": {
"schedule": { "cron": "30 4 * * 1", "timezone": "America/Vancouver" },
"credentialsSecret": "HYPERVIBE_CLOUDSQL_DRILL_CREDENTIALS",
"verificationQuery": "SELECT count(*) FROM users",
"restoreLagMinutes": 10,
"retainFailedInstanceDays": 3
}
}
}
}
}
}
The first restore-drill slice supports one GitHub canonical environment per repository. It generates a reviewed scheduled workflow that clones the exact bound primary at the declared point in time, runs the SQL check in a read-only transaction, and deletes the successful clone only after confirming its ownership labels. Failed labeled clones remain briefly for inspection and are collected by a later run. Application database bindings never change.
Use a dedicated GCP service-account JSON key, created or reviewed at
https://console.cloud.google.com/iam-admin/serviceaccounts, and store it in
the repository Actions secret named by credentialsSecret. Scope it to the
single GCP project containing the source instance. The recommended custom role
contains only:
cloudsql.instances.clone
cloudsql.instances.connect
cloudsql.instances.delete
cloudsql.instances.get
cloudsql.instances.list
cloudsql.instances.update
cloudsql.users.update
roles/cloudsql.admin also works but is broader than the drill needs.
Cloud SQL Admin API must be enabled. The connector still needs a network path;
this V1 workflow targets Hypervibe-provisioned Cloud SQL instances with public
IP connectivity. Declare a value-free GitHub Actions destination in
spec.secrets, then supply the local file only to the plan:
{
"secrets": {
"HYPERVIBE_CLOUDSQL_DRILL_CREDENTIALS": {
"principal": "github:infrastructure-owner",
"githubActions": { "repository": true }
}
}
}
hv_plan project="example" env="production" secretRefs={"HYPERVIBE_CLOUDSQL_DRILL_CREDENTIALS":"file:/absolute/path/cloudsql-drill-service-account.json"}
hv_plan blocks while the secret name cannot be observed. Once present, the
GitHub infrastructure action is billable and confirmation-gated because each
scheduled run creates a temporary Cloud SQL instance. After the generated PR
is merged, use hv_ci_status to inspect Hypervibe / db-restore-drill-production
runs and their bounded logs.
Do not temporarily change a service releaseCommand just to seed or import production data. Application containers should converge schema during startup. When startup migration is not appropriate, a release command is durable desired deploy configuration for repeatable schema work, such as migrations: { "mode": "releaseCommand", "command": "npm run db:migrate" }.
For fresh environments, declare seed/bootstrap data on the database. This is provider-neutral desired state; it works through the normal plan/apply flow for any supported hosting/database target:
{
"database": {
"provider": "supabase",
"engine": "postgres",
"seedCommand": "npm run db:seed"
}
}
hv_plan emits a visible one-shot database seed action. hv_apply runs it after the database exists as a one-off command inside the deployed service environment, then records the command hash plus seededAt on the database component. The command does not run again unless the command changes.
When the same CI-owned plan introduces Stripe runtime variables or creates a
webhook signing secret, Hypervibe converges those resources and unlocks the
reviewed release first, then reports the seed as pending. After that release is
healthy, re-run hv_plan/hv_apply; the unchanged seed command remains planned
and runs against the newly deployed image. This keeps webhook-producing fixture
creation on the application side without racing the Stripe/application boundary.
Hypervibe does not expose an imperative database migration command. Schema
migrations belong in application startup or durable declared release
configuration. Provider-to-provider data moves and database resets must be
modeled as explicit desired-state lifecycle actions before Hypervibe supports
them; they cannot bypass hv_plan/hv_apply. Re-seeding likewise requires a
reviewable desired-state change rather than a generic command runner.
The first load-balancer slice uses Cloudflare in front of two or more
equivalent public web services. The environment domain is the public
hostname; each origin continues to use its provider-issued HTTPS URL and host
header. Origins must resolve to distinct public DNS hosts; local/private hosts,
IP literals, embedded credentials, paths, nonstandard ports, and duplicate
addresses block before any load-balancer mutation. Declare it through the
normal desired-state loop:
{
"domain": "app.example.com",
"services": {
"web-a": { "workloadKind": "web", "public": true },
"web-b": { "workloadKind": "web", "public": true }
},
"loadBalancer": {
"provider": "cloudflare",
"services": ["web-a", "web-b"],
"healthCheckPath": "/health"
}
}
hv_plan observes and reconciles three explicit resources: an HTTPS health
monitor, an equal-weight random origin pool, and the zone hostname load
balancer. Pool/topology changes and initial hostname creation are marked
billable. Removing the block plans confirmed deletion of public routing before
the pool and monitor are removed. Same-name resources without durable bindings
are never adopted implicitly; adopting existing Cloudflare load-balancer
resources is outside V1, so those conflicts block until removed or renamed.
ECS Express's ALB remains provider-internal hosting ingress, not a generic
cross-origin edge load balancer; adding a second AWS-facing abstraction here
would duplicate ownership and weaken the action boundary.
Typical team flow:
.hypervibe/spec.json and, after apply, .hypervibe/bindings.json.hv_plan, and see the same desired shape and provider bindings.hv_connections when needed.Recommended default for DNS, custom domains, and email routing: use a Cloudflare Account API Token plus accountId. Cloudflare recommends Account API Tokens for automation credentials that are not associated with a specific user.
Create it from the pre-filled Hypervibe Account API Token template. The link preselects Zone Read, Zone Settings Read, DNS Edit, and Account Settings Read. Choose the target account and narrow the zone resources before creating the token.
Set these permissions and resources:
Permissions:
- Zone -> Zone -> Read
- Zone -> Zone Settings -> Read or Edit
- Zone -> DNS -> Edit
- Load Balancers Read and Load Balancers Write on the target zone (for `loadBalancer`)
- Load Balancing: Monitors and Pools Read and Write on the owning account (for `loadBalancer`)
- Zone -> Email Routing Rules -> Edit (for `email.forwarding`)
- Account -> Email Routing Addresses -> Edit (to create/verify forwarding destinations)
- Account -> Account Settings -> Read (lets Hypervibe auto-resolve accountId)
Zone Resources:
- Include -> Specific zone -> example.com
Use the generated token secret itself as CLOUDFLARE_API_TOKEN; do not use the token name, token id, or legacy Global API Key. New User API Tokens usually start with cfut_; Account API Tokens usually start with cfat_.
Connect without pasting the token into chat. If the values are in an existing .env file, reference the keys directly instead of copying them to a temporary file:
hv_connections provider=cloudflare scope="example.com" credentialsRef="dotenv:/absolute/path/.env" credentialsMap={"apiToken":"CLOUDFLARE_API_TOKEN","accountId":"CLOUDFLARE_ACCOUNT_ID"}
If the repository already uses the official Stripe Projects plugin for this Cloudflare service, select and pull the environment yourself once, then let Hypervibe map only that service's fields from the existing local output:
stripe projects env use production
stripe projects env --pull
hv_connections provider=cloudflare scope="example.com" credentialsRef="stripe-projects://production/cloudflare/workers" credentialsMap={"apiToken":"CLOUDFLARE_API_TOKEN","accountId":"CLOUDFLARE_WORKERS_ACCOUNT_ID"}
Use the exact key names reported by
stripe projects env --service cloudflare/workers; Projects may namespace a
service field to avoid collisions. Hypervibe does not run either setup command,
refresh the cache, link providers, provision services, or rotate Stripe
Projects credentials. It checks the
active environment through redacted metadata, reads only the fields Stripe
Projects declares for cloudflare/workers, and snapshots them into the
encrypted Cloudflare connection. The output file must be inside the linked
repository, non-symlinked, and owner-only (chmod 600) on POSIX. After an
intentional Stripe Projects pull or rotation, rerun the same hv_connections
call to update Hypervibe's encrypted snapshot.
Hypervibe accepts either a raw token or a copied authorization value such as Bearer <token> for Cloudflare.
If Hypervibe needs Cloudflare Registrar/domain purchase, use a User API Token instead because Cloudflare Registrar is not compatible with Account API Tokens. Create it under My Profile -> API Tokens -> Create Token -> Edit zone DNS, add the same zone permissions above, and connect it without accountId:
Open the pre-filled Hypervibe User API Token template, narrow its account and zone selectors, and add Registrar write before creating it. Cloudflare's documented template keys cover Hypervibe's base DNS permissions but not the optional Registrar, Email Routing, or Load Balancing permissions, so add only the optional capabilities the spec uses.
hv_connections provider=cloudflare scope="example.com" credentialsRef="dotenv:/absolute/path/.env#CLOUDFLARE_API_TOKEN"
If the token is valid but Hypervibe cannot confirm zone access during hv_connections, the connection is still saved and verified with a warning; hv_plan/hv_apply will surface any remaining DNS or registrar-specific blockers.
For the current desired-state GitHub model—including generic checks, autofix, pull-request review, code audit, dependency/security controls, declarative GitHub Pages with custom-domain DNS, exact token permissions, and the infrastructure PR flow—see GitHub infrastructure for beginners.
Hypervibe prepares one clear local slot per credential role. Create the
repository-management token from the
pre-filled fine-grained link (or the
pre-filled classic API link), and create the classic package token
from the pre-filled read:packages link:
HYPERVIBE_GITHUB_TOKEN=github_pat_... # fine-grained repository permissions above
NODE_AUTH_TOKEN=ghp_... # scopes: read:packages; npm also reads this name
Then connect:
hv_connections provider=github scope="owner/repo" credentialsRef="dotenv:/absolute/path/.env" credentialsMap={"apiToken":"HYPERVIBE_GITHUB_TOKEN","packageReadToken":"NODE_AUTH_TOKEN"}
If one classic PAT intentionally has repo, workflow, and read:packages,
the same value may fill both roles. Hypervibe keeps the slots separate so a
package-read credential does not silently become a repository-writing token.
HYPERVIBE_GITHUB_PACKAGES_TOKEN remains accepted when explicitly referenced
for compatibility, but Hypervibe does not generate it as a third field. Exact
references win; ambiguous fallback alias values block instead of being guessed.
For JSON credentials, use credentialsRef="file:/absolute/path/to/credentials.json".
Raw credentials={...} remains available only when the user intentionally
chooses to enter a credential in chat.
A token with only read:packages is not enough for Hypervibe CI deploy setup. It can be used as packageReadToken, but the apiToken still needs repo + workflow for classic PATs so Hypervibe can manage workflows and repository secrets.
What hypervibe uses the GitHub token for, and the permission each operation needs:
Fine-grained PATs can work for some GitHub API operations when granted the permissions in the table, but GitHub Packages/GHCR package authentication still requires a classic PAT. If you use a fine-grained PAT as apiToken, still provide a classic PAT with read:packages as packageReadToken for Railway GHCR deploys.
GitLab is selected through the canonical provider-neutral block, not a second top-level vendor object:
{
"gitRemoteUrl": "https://gitlab.com/acme/storefront.git",
"devops": {
"code": {
"provider": "gitlab",
"scope": "https://gitlab.com/acme/storefront",
"repository": { "state": "present", "management": "external" }
},
"ci": { "provider": "gitlab-ci" },
"canonicalEnvironment": "production"
}
}
The ready-for-live deploy path targets GitLab 18.1 or newer and renders the
same provider-neutral hosting recipes for Railway, Vercel, DigitalOcean App
Platform, Cloud Run, Azure Container Apps, and ECS Express. GitLab.com can use
the tagged hosted Linux runner. Self-managed GitLab uses an explicit
devops.ci.runner binding containing one numeric project-runner id, one manager
system id, a dedicated tag, and declared capabilities. Hypervibe proves that
the runner is locked, online, protected-ref-only, uncontested, and backed by
exactly one online linux/amd64 manager. GitLab does not expose executor type or
privileged-Docker mode through these APIs, so docker-privileged is an operator
attestation mirrored exactly in the runner maintenance note.
"ci": {
"provider": "gitlab-ci",
"runner": {
"mode": "self-managed",
"runnerId": "123",
"managerSystemId": "s_runner-host-1",
"tag": "hypervibe-prod",
"capabilities": ["linux-amd64", "docker-privileged"]
}
}
Create an exact-project API token with api and Maintainer access (the
GitLab.com pre-filled PAT link). Explicit managed project creation/deletion instead requires a personal token whose user owns the exact parent group, or its own personal namespace. Railway additionally needs a project deploy token with read_registry for its durable private-image pull. Store credentials outside the repository:
hv_connections provider="gitlab" scope="https://gitlab.com/acme/storefront" credentialsRef="file:/absolute/path/gitlab-connection.json"
The JSON contains apiToken, optional instanceUrl, and the deploy token's
registryUsername/registryReadToken. The first apply creates one atomic
configuration commit and merge request, then stops pending human review. After
merge, re-run plan/apply; Hypervibe proves the exact files and CI Lint include
graph before creating project-specific, environment-scoped variables.
The project must disable pipeline-variable overrides, enable forward-deployment
protection, disable rollback retries, enable its container registry for image
recipes, protect deploy branches against direct/force pushes, and—for
production—protect the GitLab environment for Maintainers. Each
hypervibe-rollback-<environment>-* protected-tag rule must allow only the exact
authenticated GitLab user; the broader Maintainer role is rejected. This
per-user rule requires GitLab Premium or Ultimate.
Immediately before any hosting API mutation, the generated deploy job uses its short-lived GitLab job token to prove its exact deployment job, pipeline, SHA, environment, and ordering through the Deployments API. Unknown identity or a newer environment deployment fails closed.
Status, bounded logs/artifacts, exact-SHA manual trigger, and evidence-backed
rollback use the same hv_ci_status, hv_ci_trigger, and hv_rollback
commands as GitHub. To remove managed CI, keep devops.ci selected and first
change the environment deploy strategy to manual: Hypervibe reviews removal
of its generated files, waits for active jobs, deletes each exact owned
variable with confirmation, and finally removes its binding. Then remove
devops.ci. Repository lifecycle is separately explicit:
"repository": {
"state": "present",
"management": "managed",
"visibility": "private",
"defaultBranch": "main"
}
Creation makes one initialized remote project and uses its verified numeric id
as the durable identity. The declared default branch and visibility must also converge;
setting drift blocks explicitly, and an acknowledged nonconverged project keeps
its durable binding so creation is never retried blindly. It does not push or
rewrite local Git history. Before deletion,
tear down CI and branch deploys, then set state to absent; create/delete
actions require exact action-id confirmation. GitLab.com keeps the binding
during its 30-day deletion retention, while self-managed deletion is verified
absent before local state is removed. If scheduled self-managed deletion is
acknowledged but permanent removal fails, Hypervibe retains the binding and
plans another confirmed retry against the same numeric id and full path. All of
this remains ready-for-live, not
publicly supported, until recent opt-in live contracts pass for the exact
GitLab offering, runner mode, and hosting recipe.
deploy.strategy: "branch" defaults to deploy.trigger: "ci". Hypervibe sets up push deploys through the selected CI provider and calls hosting APIs directly; it does not install or depend on provider CLIs.
Provider-native source ownership is exclusive. Only an explicit
deploy.trigger: "native" may keep a repository connected at the hosting
provider. Manual and CI modes stage source reconciliation before every other
mutation: Railway disconnects through its provider API, while Vercel and
DigitalOcean block with manual-disconnect guidance.
Unknown source observation blocks for all three providers. After the source-only
plan converges, run hv_plan again to review storage, variable, workflow, or
deployment work separately.
Typical setup:
deploy: { strategy: "branch", branch: "main" } or an explicit trigger: "ci". For GitHub Actions, this branch must be the repository's default branch so GitHub can dispatch the managed workflow.hv_apply first so Hypervibe records provider project, environment, and service ID bindings.deploy.strategy="branch" and deploy.trigger="ci" with hv_spec, then run hv_plan and hv_apply.requiredSecrets, syncedEnvironmentSecrets, and requiredVariables. Hypervibe syncs deployment credentials and migration database URLs into the selected GitHub environment when its connections are verified. Repository build secrets use their separate declared scope.Provider workflow behavior:
Every generated workflow checks the selected environment's committed desired
state before building. Hypervibe stores the last successfully applied
environment contract hash in the environment-scoped GitHub Actions variable
HYPERVIBE_APPLIED_SPEC_HASH. Code-only commits retain the same hash and
continue to auto-deploy to staging. A commit that changes the environment
contract stops before image build until the exact commit is reconciled:
hv_plan and review the environment plan.hv_apply so all desired-state actions complete and the final hash
marker advances.hv_ci_trigger, inspect it with hv_ci_status,
and verify it with hv_health.For project-backed checks, hv_health keeps the requested HTTP result separate
and also reports the latest bound deployment status for every declared
environment and service. This lets a healthy staging endpoint surface a failed
production build; provider read failures and pending states remain unknown.
The marker is environment-specific: production-only desired-state changes do not block staging. Production workflows remain manual and enforce the same reconciliation check for the promoted SHA.
Unreleased promotion support: to require a fresh full test run before a manual GitHub Actions promotion, add
deploy.promotionTests: { workflow: ".github/workflows/test.yml" } alongside an
explicit deploy.promoteFrom. The same-repository reusable workflow mu
Desired-state infrastructure orchestration through CLI and MCP
{ "mcpServers": { "hypervibe-hypervibe": { "command": "npx", "args": [ "-y", "@hypervibe/[email protected]" ] } }}Araçlar
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
@hypervibe/hypervibe yerel olarak stdio üzerinden çalışır.
Son kontrol: 2026-10-28. Desired-state infrastructure orchestration through CLI and MCP