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 vulns <app>`: security scan findings — package, installed version,
    and "update to <version>" when a fix is released; bump the dependency (or the
    Dockerfile base image) and push, the next build is re-scanned automatically
  - `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.
- Apps are private by default. A path that must answer without a login goes in
  auth.public_paths in apphaven.yaml, but that is only a SUGGESTION: it does
  nothing until a project admin adds it in the console. Say what you suggested
  and why, then check `apphaven app <app>` to see if it was granted. A redirect
  to the login page on an ungranted path is correct behaviour, not a bug.
- 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.

When a newer CLI is available, any command prints a one-line notice on stderr (at most once a day; command output on stdout is never touched, so --json pipelines are safe). Rerun the installer to update. Set APPHAVEN_NO_UPDATE_NOTIFY=1 to silence the notice, for example in CI.

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.

6. Suggesting a public path

Most apps are private, so every request needs an AppHaven login. When an agent adds something that has to answer without one (a webhook receiver, a health probe, an API called with its own keys), it needs a public path. An agent cannot open one. It can only ask.

The loop has three steps, and the third one is the part that is easy to skip.

1. Suggest it in the manifest. Add the path, with a reason, to apphaven.yaml:

auth:
  public_paths:
    - path: /webhooks/stripe
      reason: Stripe webhook receiver, verified by signature

This changes nothing on its own. It puts the request, and its reason, on the app's Access card in the console.

2. Tell the human what you asked for and why. The person reading your summary is the only one who can grant it, in the console, as a project administrator. Say which path you suggested, what calls it, and how your code authenticates the caller. An unexplained suggestion is one a reviewer should refuse.

3. Read back whether it was granted. apphaven app <name> shows the app's access mode, the paths that are actually public, and any suggestion still waiting:

Access:       Private (production and previews require login)
Public paths: /healthz, /api/*

Suggested public paths (not active - a project admin must add these in the console):
  /webhooks/stripe   Stripe webhook receiver

--output json carries the same fields for scripted checks.

A 302 on an ungranted path is correct, not a bug

Until an administrator adds your suggested path, a request to it redirects to the AppHaven login page. That is the platform doing exactly what it should. Do not debug it, do not retry it, do not re-suggest the path in a new commit, and never work around it by weakening the app. Check apphaven app, and if the path is still listed as suggested, the answer is simply that nobody has granted it yet.

Once a path is granted, it takes effect on the next deployment of the branch, and requests to it arrive with no X-Apphaven-Auth header at all. Your code must authenticate them itself. See the authentication reference.

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.