> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-install checks for AI agents

> Checks an AI coding agent runs before starting an agentic install of AppSignal, and what to do when one fails.

# Pre-install checks

Run these before reading an install file or editing any code. Each one catches a
failure that is expensive to diagnose later. By the time config is written and
packages are installed, the only symptom is "no data arrived." Finding the same
problem now costs one command.

Stop and tell the user when a check fails. Do not work around a failed check by
guessing, skipping it, or fixing it yourself unless the check's own entry says so.
The whole point is that these are things you cannot safely decide alone.

Before running these checks, identify the values required by the selected integration.
Ask the user for any value they have not already provided. Tell them where to find it:

* Back-end integrations use an Organization-level Push API key from the
  [organization's API keys](https://appsignal.com/redirect-to/organization?to=admin/api_keys).
* Browser integrations use a Front-end API key from the app's
  [Push & Deploy settings](https://appsignal.com/redirect-to/app?to=api_keys).
* PHP, Go, Java, and other OpenTelemetry integrations use a collector endpoint from the
  organization's [Hosted Collectors settings](https://appsignal.com/redirect-to/organization?to=admin/hosted_collectors).

Do not write configuration until the user has supplied the required values and
confirmed the proposed app name and environment when the integration uses them. Ask
again only when a supplied value is malformed or conflicts with an existing
installation.

## 1. The system clock is correct

Data carries the timestamp of the machine that produced it, so a clock that is minutes
out records traces and metrics under the wrong time for as long as the drift lasts, and
stops anomaly detection opening and closing alerts for that app. A container or CI
runner with a stopped or unsynced clock is the common case, not a rare one.

Compare local time to network time without installing anything:

```bash theme={null}
date -u
curl -sI https://appsignal.com | grep -i '^date:'
```

A difference of a few seconds is normal. A difference of minutes or more means the
clock is wrong. You cannot fix the system clock yourself. It is a host-level change
outside the install's scope and often needs privileges you do not have. Report the
drift you found and stop; let the user fix the clock or tell you to proceed anyway.

## 2. AppSignal is not already installed for this app

Installing on top of an existing integration is only risky if it changes the
`push_api_key`. Reinstalling with the same key is harmless: config gets rewritten,
but data keeps going to the same application. If the key changes, data silently
moves to a new application. The one already running (possibly production) stops
receiving data, which looks like an outage until someone finds the new entry in the
dashboard.

Check for existing signal before writing anything:

* A config file already present: `config/appsignal.rb` or `config/appsignal.yml`,
  `config/appsignal.exs`, `appsignal.cjs`, `appsignal.js`, `appsignal.ts`,
  `__appsignal__.py`, or `config/appsignal.php`.
* The package already in the manifest: `appsignal` in `Gemfile`/`Gemfile.lock`,
  `mix.lock`, or `requirements.txt`/`pyproject.toml`; `@appsignal/nodejs`,
  `@appsignal/javascript`, `@appsignal/browser`, or an `@appsignal/plugin-*` in
  `package.json`; `appsignal/appsignal-php` in `composer.json`.
* An `APPSIGNAL_PUSH_API_KEY`, or another `APPSIGNAL_*` variable, already set in `.env`,
  shell profiles, or deployment config.
* AppSignal or OpenTelemetry imports, initialization calls, preload flags, Java agents,
  OTLP exporters, or AppSignal endpoints in source code, start scripts, containers, CI,
  or deployment config.

If any of these exist, inspect the existing setup before changing anything. Compare its
relevant key with the key the user provided when both values are available: the
Push API key for back-end integrations, or the Front-end API key for browser
integrations. When the existing integration is compatible and the keys match, preserve
its configuration and complete only the missing steps. Tell the user what you found and
what you completed. Stop and ask how to proceed when the key differs or cannot be
compared, the package or destination conflicts, or the project may be adding a second
integration intentionally. Do not overwrite a key, duplicate an integration, or migrate
between AppSignal packages without confirmation.

## 3. Git is in a clean, known state

An install touches several files across a few steps: manifest, config, boot file. If
something goes wrong partway, the only way to cleanly undo it is a diff that contains
nothing but the install. Starting on a dirty tree makes that diff impossible to
separate from whatever was already in progress.

With no `.git` directory this check does not apply: `git status` failing with `not a
git repository` is not a failed check. Say so and go on to check 4.

```bash theme={null}
git status --porcelain
git branch --show-current
```

* **Uncommitted changes already present:** do not commit, stash, or discard them; they
  are not yours to touch. Tell the user what is already modified, then carry on and name
  the files you changed when you report back. Stop and ask first only when a file the
  install has to write is already modified.
* **Current branch is not `main` or `master`:** ask whether to continue on it or
  switch. Installing on top of unrelated in-progress feature work risks mixing two
  unrelated changes into one diff, and later makes both harder to review or revert.
* **Clean tree on `main`/`master`:** create a feature branch for the install itself
  (for example `git checkout -b add-appsignal`) so the change stays isolated and
  reviewable, unless the user has asked you to commit directly.

## 4. The data destination is reachable

Config written against an endpoint the app can never reach produces the same silent
"no data arrived" outcome as a wrong API key, but looks identical to a config mistake
until you rule out the network separately. Corporate proxies, restrictive egress
rules, and self-hosted collectors are the common causes, worth ruling out before
writing any config, not after the final send-test-data step fails.

Choose the destination for the integration you identified:

* Browser JavaScript: `https://appsignal-endpoint.net`
* Ruby, Elixir, Node.js, or Python without a configured collector: `https://push.appsignal.com`
* PHP, Go, Java, or any integration configured for OpenTelemetry: the collector endpoint the user supplied

```bash theme={null}
curl -sS -o /dev/null -w '%{http_code}\n' "<DESTINATION_URL>"
```

Any HTTP status code, including a 404, means the network path works: the request
reached the server. A curl-level failure (connection refused, timeout, DNS
resolution failure, TLS error) means it does not. This check proves only that the host
is reachable; it does not validate the key or prove that the application can send data.

If unreachable, stop. Report exactly what curl reported (timeout, DNS failure, TLS
error, or connection refused) and ask the user how to proceed. A proxy or firewall
exception is theirs to fix, not yours to route around.

## 5. The user has supplied the required values

Before starting, inventory the values the user supplied. Back-end installs need an
Organization-level Push API key, app name, and environment; Go and Java also need a
collector endpoint and service name, while PHP needs a collector endpoint. Browser
installs need only the Front-end API key because it already selects the AppSignal app and
environment. Do not ask the user to repeat a value that is already present. If a required
value is missing, malformed, or conflicts with the project, ask before editing. Never
invent or derive one: see the
"Replace `<YOUR_PUSH_API_KEY>`…" guidance in
[https://docs.appsignal.com/agents/new-application.md](https://docs.appsignal.com/agents/new-application.md) for what each language needs
and why a guessed value is worse than no install at all.