Agent integration

Give your coding agent its own window onto AppHaven. With the apphaven CLI and the AppHaven skill installed, an agent working in your repository can answer for itself: is the app deployed, on what URL, did the build succeed, why did it crash, what is it logging right now. It can also check apphaven.yaml against the platform's validation before anything is pushed.

Everything the agent gets is read-only by design. The CLI cannot deploy, restart, change configuration, or read secret values. Deploys keep flowing through git push and the console, exactly as described in Building with AI agents.

The fast path: install the plugin (step 1) and ask your agent to "set up AppHaven access". The skill walks it through installing the CLI and starting the login; your only step is approving the request in your browser. Steps 2 and 3 are the manual equivalent.

1. Teach your agent

Claude Code: install the AppHaven plugin from the marketplace.

/plugin marketplace add apphaven-eu/claude-plugins
/plugin install apphaven

The plugin ships the skill: what the CLI can do, how to read build and runtime logs, how to author apphaven.yaml, and where these docs live. Updates arrive through the marketplace.

Codex and other agents: paste this block into the instructions file your agent reads (AGENTS.md or equivalent). Keep the markers so you can replace the block when it changes.

<!-- apphaven:begin -->
## AppHaven (this app's hosting platform)
- This repo deploys on AppHaven. Pushing a branch creates a preview deployment
  on its own URL; the production branch deploys to production.
- The `apphaven` CLI gives you read-only visibility. Useful commands
  (all support --json; `apphaven <cmd> --help` is authoritative):
  - `apphaven status <app>`: deployment phase, branch, URL
  - `apphaven build-log <app>`: latest build log (failures are at the tail)
  - `apphaven crash-log <app>`: what to read when a deployment is Failed
  - `apphaven logs <app> --service <svc>`: container output
  - `apphaven variables <app>`: config names (secret values are never shown)
  - `apphaven validate`: validate apphaven.yaml before pushing
- Debugging order: status, then build-log (build failed), then crash-log
  (deploy failed), then logs (running but misbehaving), then variables
  (missing config).
- The CLI is read-only: it cannot deploy, restart, or change anything.
  To ship, push to git. Never try to work around this.
- If a command says "Not logged in", run `apphaven login` and let the human
  approve in the browser. Never echo credentials.
- apphaven.yaml is strictly validated; unknown fields are errors. Reference:
  https://docs.apphaven.eu/reference/manifest (full docs index for agents:
  https://docs.apphaven.eu/llms.txt)
<!-- apphaven:end -->

2. Install the CLI

One line, no dependencies: the CLI is a single static binary.

# Linux, macOS, and WSL
curl -fsSL https://raw.githubusercontent.com/apphaven-eu/cli/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/apphaven-eu/cli/main/install.ps1 | iex

Verify with apphaven version. Your agent can run the installer for you; its normal command-approval flow is your consent gate.

3. Log in

apphaven login

Your browser opens on auth.apphaven.eu and asks you to approve: AppHaven CLI requests read access to your projects, applications, deployments and logs. That grant is the whole surface: read-only, scoped to the projects you are a member of. The CLI stores its credentials in your user profile (~/.config/apphaven/, or %APPDATA%\apphaven on Windows) and refreshes them automatically.

It is safe to let an agent run apphaven login: the approval happens in your browser, and credentials never appear in the command's output, so there is nothing for the agent to see or echo.

You stay in control afterwards: the CLI access page in your account on auth.apphaven.eu lists every active CLI login with its last use, and one click revokes it. apphaven logout does the same from the terminal.

4. What the agent can (and cannot) do

Can read	Can never do
Projects and applications you are a member of	Deploy, stop, or restart anything
Deployment status, branches, and URLs	Create, change, or delete applications
Build logs, crash reports, container output	Change variables or any configuration
Variable names (secret values stay masked)	Read secret values
The activity timeline	Act on projects you are not a member of

Reads follow your project membership. Revoking the grant (or losing membership) cuts the agent off at the next refresh.

5. Writing apphaven.yaml with an agent

Two tools keep a generated manifest honest:

• apphaven validate runs the same fail-closed validation the platform applies when you deploy, and prints the same errors. "The agent's manifest looked fine but the deploy was rejected" cannot happen. The skill teaches agents to validate before every push.

• The JSON Schema gives editors and agents inline checking as the file is written. Add one comment line at the top of apphaven.yaml:

  # yaml-language-server: $schema=https://docs.apphaven.eu/schemas/apphaven.schema.json

The schema checks structure; apphaven validate is the authority. It also catches what a schema cannot, like dependency cycles or a ${...} reference to a service that doesn't exist. The manifest reference documents every field.

For agents that read documentation directly: https://docs.apphaven.eu/llms.txt is an index of every page on this site, and llms-full.txt is the whole documentation in one file.

Troubleshooting

• Not logged in. Run "apphaven login". Exactly that; the grant may have been revoked or expired after long disuse.
• The browser never reaches the terminal (firewall, SSH box, container): run apphaven login --manual, open the printed URL on any device, and paste the code the approval page shows you back into the terminal.
• 403: you are not a member of that project, or the grant was revoked.
• 429: the CLI is rate-limited per user; agents should respect the Retry-After header (apphaven status --wait and logs --follow do this automatically).
• "ambiguous app name": two apps share a name across your projects; pass --project.