# Helvstack

Helvstack is a Swiss-first app deployment control plane. Agents should use the CLI or the agent API, not browser automation, for deployments.

Agent-native onboarding:
- Human and agent guide: https://helvstack.com/agent
- Canonical deploy skill: https://helvstack.com/agent/helvstack-agent-deploy/SKILL.md
- Public skill repository: https://github.com/ElyzeSolutions/helvstack-skills
- skills.sh listing: https://www.skills.sh/elyzesolutions/helvstack-skills/helvstack-agent-deploy
- Standard install: npx skills add ElyzeSolutions/helvstack-skills --skill helvstack-agent-deploy -g -y
- Structured onboarding manifest: https://helvstack.com/agent/manifest.json
- The skill is the execution contract: inspect, scope auth, plan, apply idempotently, wait, verify, and return evidence.

Public CLI distribution:
- Browsable command reference: https://helvstack.com/docs/cli
- Plain-text command reference: https://helvstack.com/docs/cli.txt
- npm: npm install --global helvstack (https://www.npmjs.com/package/helvstack)
- Python toolchains: uv tool install helvstack (https://pypi.org/project/helvstack/)
- Checksummed platform binaries: https://github.com/ElyzeSolutions/helvstack-cli/releases
- Verify the installed build: helvstack --json version

Canonical prompt:

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.

Primary agent flow:
- Install the agent skill with the standard skills CLI, then install the public Helvstack CLI with npm, uv, or a checksummed release binary.
- For first-project deployment, install the public Agent Skill above or read its canonical hosted URL. Private operational docs are only for authorized Helvstack colleagues working inside the monorepo.
- Run: helvstack auth login --project <project> --environment production
- For custom browser control, run: helvstack --json auth start --project <project> --environment production, open verificationUriComplete, then poll with helvstack --json auth poll --device-code <deviceCode>.
- Approve the browser prompt at console.helvstack.com with Google sign-in.
- Poll responses expose browser.opened and browser.signedIn so agents can track the Better Auth Google approval page without scraping HTML.
- Use --json, --idempotency-key, --project, --environment, and explicit service names.
- Plan before mutating: deploy --plan, env set --plan, domain add --plan.
- 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.
- Before a source build, use registry-provider set ghcr or gitlab-registry with write-only environment credentials that can push and pull the destination. Set services.<name>.build.destination for an explicit image path.
- For dotenv files, use env import --from-file with --plan first. Never print env values.
- For multi-service apps, deploy and verify every required service explicitly.
- MCP clients can run: helvstack mcp serve
- The signed-in console exposes six scoped WebMCP tools, including helvstack.get_agent_guide for in-browser discovery.

Agent API:
- CLI auth stores a scoped token in .helvstack/config.json.
- The stored API URL is https://console.helvstack.com/api/agent.
- API paths under /api/v1 are proxied through the console agent boundary after org/project/environment/scope checks.
- OpenAPI is available through: helvstack openapi
- Capabilities are available through: helvstack capabilities

Safety:
- Secret values are write-only.
- Mutations should send Idempotency-Key.
- Operation responses should be polled until succeeded, failed, or canceled.
- Custom domains require ownership verification and DNS routing before activation.
- Cloudflare for SaaS is the target customer-domain edge; direct Kubernetes TLS is the fallback.
- Operator-only ops.helvstack.com is not the SaaS agent surface.

More: /llms-full.txt