# Helvstack Agent Contract ## Surfaces - https://helvstack.com/agent: public human-and-agent onboarding with one copyable prompt. - https://helvstack.com/agent/helvstack-agent-deploy/SKILL.md: canonical public Agent Skill for deployment. - https://github.com/ElyzeSolutions/helvstack-skills: public Git source for the skill. - https://www.skills.sh/elyzesolutions/helvstack-skills/helvstack-agent-deploy: skills.sh discovery, security audits, and install surface. - https://helvstack.com/agent/manifest.json: structured onboarding discovery metadata. - https://helvstack.com/docs/cli: browsable CLI command map with copy and AI actions. - https://helvstack.com/docs/cli.txt: plain-text CLI reference for agents and retrieval. - console.helvstack.com: SaaS console for humans and agent-token approval. - console.helvstack.com/api/agent: scoped agent API proxy. - ops.helvstack.com: private operator control plane; do not use for normal SaaS agent deployments. - git.helvstack.com: GitHub/GitLab callback and webhook edge. ## Canonical onboarding prompt ```text Set up and deploy this repository on Helvstack. Read https://helvstack.com/agent/helvstack-agent-deploy/SKILL.md and follow it exactly. Inspect the repository before changing files. Create or update helvstack.yml for every required service, use browser-approved access scoped to this project and environment, plan every remote mutation, apply with stable idempotency keys, wait for terminal operation states, then verify health, logs, events, and public URLs. Never print secret values. Ask me only when browser approval is ready or when a product choice cannot be inferred safely. ``` The public prompt and skill are designed to work even when the user does not know which Helvstack command to ask for. The agent must inspect the repository, represent every required service, obtain scoped access, plan before apply, use idempotency keys, wait for terminal operations, and return verification evidence. ## Install the Agent Skill ```bash npx skills add ElyzeSolutions/helvstack-skills --skill helvstack-agent-deploy -g -y npx skills use ElyzeSolutions/helvstack-skills --skill helvstack-agent-deploy ``` The first command installs globally for supported agents detected by the skills CLI. The second resolves the same public skill for a one-off run without a persistent install. ## Install the Helvstack CLI The CLI is public. Install it from either ecosystem package registry: ```bash npm install --global helvstack # or uv tool install helvstack helvstack --json version ``` - npm package: https://www.npmjs.com/package/helvstack - PyPI package: https://pypi.org/project/helvstack/ - Checksummed platform binaries: https://github.com/ElyzeSolutions/helvstack-cli/releases Release downloads include `checksums.txt`. The npm and PyPI launchers select the current platform binary and verify its SHA-256 checksum before execution. ## CLI Login ```bash helvstack auth login --project --environment production helvstack --json auth start --project --environment production helvstack --json auth poll --device-code helvstack --json auth poll --device-code --wait helvstack auth status --json helvstack auth logout --revoke ``` The login command opens a browser authorization page. If the user is not signed in, the console sends them through Google sign-in and then returns to the agent approval page. The CLI polls until approval and stores a scoped token in .helvstack/config.json. Agents that need direct control over the browser can use auth start and auth poll instead. The start response includes verificationUriComplete, pollUri, apiUrl, deviceCode, userCode, expiresAt, and intervalSeconds. Pending poll responses include browser.opened and browser.signedIn, allowing agents to detect whether the opened Better Auth Google page has reached the signed-in approval screen without scraping HTML. Authorized poll responses store the one-time hvs_agent token locally by default without echoing it; pass --store=false only when a direct API client intentionally needs to receive the token. Use logout with --revoke when retiring a token; plain logout only removes local config. ## First Project For a new user or agent deploying a first app, use the public skill. Authorized colleagues can also use the private monorepo's operational guide. Minimal app-owned config: ```yaml project: aegress environment: production services: web: type: web repository: https://github.com/ElyzeSolutions/aegress branch: main rootDirectory: . watchPaths: - . dockerfile: Dockerfile port: 3000 healthcheck: /api/health ``` Then run services validate, services apply --plan, services apply, deploy --plan, deploy, status, logs, and events with --json and stable idempotency keys. For multi-service apps, deploy every required service and verify every required service reaches active. ## Deploy ```bash helvstack --json capabilities helvstack --json deploy --service web --plan helvstack --json --idempotency-key deploy- deploy --service web --no-wait helvstack --json operations stale ``` ## Environment Variables ```bash helvstack --json env set API_BASE_URL=https://example.com --service web --plan helvstack --json --idempotency-key env-api-base-url env set API_BASE_URL=https://example.com --service web --no-wait helvstack --json env import --from-file deploy/production.env --plan ``` Secret values are write-only. Do not log or echo them. ## Registry Credentials Managed Harbor hosting is deferred. GitHub source builds default to the repository owner's GHCR namespace; GitLab source builds default to that project's GitLab Container Registry path. Configure the matching environment-scoped registry provider before apply with credentials that can push and pull the destination. Set `services..build.destination` in `helvstack.yml` for an explicit image path; Helvstack persists it for automatic deploys. For GHCR: ```bash export HELVSTACK_REGISTRY_USERNAME= export HELVSTACK_REGISTRY_TOKEN= helvstack --json registry-provider set ghcr --plan helvstack --json --idempotency-key registry-ghcr registry-provider set ghcr --no-wait helvstack --json registry-provider get ghcr ``` Reads return metadata and fingerprints only. Agents may also use dockerhub or gitlab-registry when appropriate. Never copy a platform-wide registry credential into a tenant environment. ## Agent Scopes Default deploy tokens include read, plan, deploy, variables:write, domains:write, registry:read, registry:write, and logs:read. Stateful automation should request only the scopes it needs. The deploy scope covers the exact environment attachment and target mutations used by services apply. Service-exposure changes require both deploy and domains:write because they can change public ingress; project-level Tailnet credential management still requires tailnet:write. - db:read / db:write for database policies, reports, backups, and restores. - cache:read / cache:write for Redis or Valkey lifecycle, backups, and restores. - object-storage:read / object-storage:write for object inventory, lifecycle cleanup, and credential rotation. - volumes:read / volumes:write for persistent volume inventory and volume mutations. - backups:write for backup creation or retention cleanup across database, cache, and volume resources. - restores:write for restore, restore-drill, restore-target cleanup, and restore policy mutations. ## Domains ```bash helvstack --json domain add app.example.com --service web --port 3000 --plan helvstack --json domain verification app.example.com --service web helvstack --json domain verify app.example.com --service web --no-wait helvstack --json domain cutover-plan app.example.com --service web helvstack --json domain remove app.example.com --service web --plan helvstack --json domain remove app.example.com --service web --no-wait ``` Custom domains require ownership verification and routing DNS before activation. Subdomains normally use CNAME. Apex domains need CNAME flattening, ALIAS/ANAME, Cloudflare for SaaS Apex Proxying, or the active Helvstack direct-edge fallback. Guided DNS with copied TXT/certificate/routing records remains the default. Connected DNS is optional: a customer can store an environment-scoped Cloudflare zone token, and Helvstack applies or deletes only matching Helvstack-owned TXT/routing records for that zone. Generated Helvstack hostnames and manual DNS setup stay available without connected DNS. Domain removal deletes Helvstack-managed ingress and frees the hostname; connected DNS cleanup is scoped to exact Helvstack target records and leaves MX, SPF, DKIM, DMARC, nameservers, and unrelated customer records untouched. Cloudflare for SaaS is the target customer-domain edge; direct Kubernetes TLS is the fallback. ## API After login, .helvstack/config.json contains: ```json { "apiUrl": "https://console.helvstack.com/api/agent", "apiToken": "hvs_agent_...", "project": "", "environment": "production" } ``` Direct API clients send: ```http Authorization: Bearer hvs_agent_... Idempotency-Key: stable-client-retry-key ``` Then call the normal Helvstack API paths under the agent proxy, for example: ```text GET /api/agent/api/v1/capabilities POST /api/agent/api/v1/projects/{project}/environments/{environment}/services/{service}/deployments/plan POST /api/agent/api/v1/projects/{project}/environments/{environment}/services/{service}/deployments ``` ## MCP Local MCP is available after CLI login: ```bash helvstack mcp serve ``` It uses stdio JSON-RPC, reads the same .helvstack/config.json, and wraps the same scoped console agent API. It does not receive operator credentials. Current tools: - helvstack_capabilities - helvstack_api_request - helvstack_service_status - helvstack_logs - helvstack_deployment_plan - helvstack_deploy - helvstack_operation_get - helvstack_env_list - helvstack_env_set - helvstack_domains - helvstack_domain_cutover_plan - helvstack_domain_verify_plan Use helvstack_domains to inspect current generated and custom hostnames. Use helvstack_domain_cutover_plan before moving customer DNS; it returns DNS record rows, provider hostname status, certificate status, blockers, fallback hostnames, and rollback steps. Use helvstack_domain_verify_plan before applying TXT ownership verification through the CLI or scoped API. Use helvstack domain remove --service --plan before removing a custom domain; generated domains are managed fallbacks and should remain available.