# Set up DeployAngel: a guide for coding agents

You're a coding agent setting up DeployAngel for the repository you're working
in. DeployAngel verifies every deploy in production: an agent inside the app
reports a small summary each minute, and DeployAngel compares each release
with the last healthy one, then says whether the deploy actually worked.

The person who sent you here gave you a one-time **setup code**
(`da_setup_…`) from DeployAngel's dashboard. In step 3 you redeem it for two
tokens, which the `deployangel` command saves without showing them to you:

- the **app token** (`DEPLOYANGEL_TOKEN`): the running app needs it in
  production, on every process (web servers and job workers);
- a **"CI deploys" token** (`DEPLOYANGEL_API_TOKEN`): for CI and the
  `deployangel` command: registering deploys, waiting for verdicts, and
  `deployangel doctor`.

If you weren't given a code, stop and ask for one: the person gets it from
"Set up with your coding agent" on the app's page in DeployAngel. A code
works once, for an hour.

## Rules

- **Never print a token.** Don't show `.deployangel/credentials.json`, and
  don't run `deployangel token` on its own: use it only inside command
  substitution or a pipe, as below, so the value never appears in your
  output or this conversation.
- **Never commit a token** or write one into a tracked file. Use the host's
  secrets or CI secrets.
- **Ask before** setting secrets on the user's host or CI, changing production,
  or deploying. Say exactly what you'll run.
- Don't remove or rewrite the user's existing configuration. Add to it.
- Full documentation: https://www.deployangel.com/docs. Each step below links
  its section.

## 1. Find the framework and the host

Framework:

| Look for | Framework |
|---|---|
| `Gemfile` with `rails` | Rails 7.1+ on Ruby 3.1+ |
| `Gemfile` with `hanami` | Hanami 2.2+ on Ruby 3.1+ |
| `Gemfile` with `sinatra` (and no `rails` or `hanami`) | Sinatra 3.0+ on Ruby 3.1+ |
| `manage.py`, or `django` in the Python dependencies | Django 4.2+ |
| `fastapi` in the Python dependencies | FastAPI 0.100+ |
| `flask` in the Python dependencies | Flask 2.3+ |
| a `.csproj` with `Sdk="Microsoft.NET.Sdk.Web"` (or a `Microsoft.AspNetCore.App` framework reference) | ASP.NET Core on .NET 8+ (Hangfire 1.8+ for jobs) |

Anything else isn't supported yet: tell the user and stop.

Host, from files in the repository (ask if it's unclear):

| Look for | Host |
|---|---|
| `config/deploy.yml` with `service:` | Kamal |
| `Procfile` and a Heroku remote, `app.json`, or the user says so | Heroku |
| `render.yaml` | Render |
| `fly.toml` | Fly.io |
| `Capfile` | Capistrano |
| `Dockerfile` with compose, ECS, Kubernetes, or Cloud Run files | Containers |
| `.ebextensions/` or `.elasticbeanstalk/` | Elastic Beanstalk |
| none of these | Ask the user how they deploy |

## 2. Install the agent

Rails: add the gem, then run `bundle install`. Nothing else is needed.

```ruby
# Gemfile
gem "deployangel"
```

Hanami: add the gem (0.1.30 or later) and run `bundle install`, as for Rails,
then install it in the app's class in `config/app.rb`:

```ruby
# config/app.rb
require "hanami"
require "deployangel/hanami"

module Bookshelf
  class App < Hanami::App
    DeployAngel::Hanami.install(self)
  end
end
```

Use the app's own module name. It starts reporting when the app boots.

Sinatra: add the gem (0.1.30 or later) and run `bundle install`, then
register the extension in each app class, before its routes (at the top
level of a classic app, after `require "sinatra"`):

```ruby
require "deployangel/sinatra"

class Bookshelf < Sinatra::Base
  register DeployAngel::Sinatra
end
```

Python: add `deployangel` to the project's dependencies (requirements file,
`pyproject.toml`, or the lock tool the project uses), then add one line for
the framework:

```python
# Django: settings.py
INSTALLED_APPS = [
    # ...
    "deployangel.django",
]

# FastAPI, where the app is created
import deployangel.fastapi
app = FastAPI()
deployangel.fastapi.init(app)

# Flask, where the app is created
import deployangel.flask
app = Flask(__name__)
deployangel.flask.init_app(app)
```

Celery outside Django: add `deployangel.celery.init(celery_app)` where the
Celery app is created. RQ: run workers with `rq worker -w deployangel.rq.Worker`.

.NET: add the package to the app's project (each one that runs as a process:
the web app, and any worker service), and register it where the host is built:

```bash
dotnet add package DeployAngel
```

```csharp
// Program.cs
builder.Services.AddDeployAngel();
```

Hangfire: also `dotnet add package DeployAngel.Hangfire` in the project that
configures Hangfire, and `UseDeployAngel()` in its configuration:
`builder.Services.AddHangfire(config => config.UseDeployAngel() /* ...the existing storage setup */);`.
A process that only runs Hangfire jobs needs both `AddDeployAngel()` and
`UseDeployAngel()`. Keep the `.pdb` files `dotnet publish` writes (the
default; don't set `DebugType` to `none`): the agent reads them to map
exceptions, routes, and jobs to source files. It reports only when the host's
environment is `Production`; to report from staging too, use
`AddDeployAngel(options => { options.Environments = new[] { "production", "staging" }; })`.
Details: https://www.deployangel.com/docs#install

In the commands below, a Ruby app runs `bundle exec deployangel`; a Python app
runs `deployangel` (or `uv run deployangel`, `poetry run deployangel`); a .NET
app runs `deployangel` from the .NET tool, installed once with
`dotnet tool install --global DeployAngel.Tool`. Written here as `deployangel`.

## 3. Redeem the setup code

```bash
deployangel setup --code=da_setup_…
```

It saves both tokens to `.deployangel/credentials.json` in the project,
readable only by the user and kept out of git (the directory ignores itself),
and prints neither. From then on, the `deployangel` command and its MCP
server use the saved token, and `deployangel token app` (or `api`) prints a
token for a pipe or `$(...)`. If it says the code is invalid, used, or
expired, ask for a new one.

The running app doesn't read this file. It reads its token only from
`DEPLOYANGEL_TOKEN` in its own environment, which step 4 sets.

## 4. Give production the app token

Set `DEPLOYANGEL_TOKEN` on every process that runs the app. Ask first.

| Host | How |
|---|---|
| Kamal | Add `DEPLOYANGEL_TOKEN` under `env: secret:` in `config/deploy.yml`, and `DEPLOYANGEL_TOKEN=$(deployangel token app)` to `.kamal/secrets`, which Kamal evaluates where `kamal deploy` runs. To deploy from CI, store it as a CI secret too: `deployangel token app \| gh secret set DEPLOYANGEL_TOKEN`, and have `.kamal/secrets` read `$DEPLOYANGEL_TOKEN` there. |
| Heroku | `heroku config:set DEPLOYANGEL_TOKEN=$(deployangel token app)`, plus `heroku labs:enable runtime-dyno-metadata` and `heroku labs:enable runtime-dyno-build-metadata` so the agent knows its release. With the DeployAngel add-on, the token is already set. |
| Fly.io | `fly secrets set DEPLOYANGEL_TOKEN=$(deployangel token app)` |
| Elastic Beanstalk | `eb setenv DEPLOYANGEL_TOKEN=$(deployangel token app)` on each environment, web and worker tiers. |
| Containers | Pass it into the container's environment from a secret: a Kubernetes Secret (`kubectl create secret generic deployangel --from-literal=DEPLOYANGEL_TOKEN=$(deployangel token app)`), the ECS task definition's secrets, compose's `environment:` from an env file git ignores, or Cloud Run's `--set-env-vars`. |
| Render, other dashboards | You can't set it from here. Ask the user to run `deployangel token app` in **their own terminal**, not through you, and paste it into the web service's and each worker's environment (on Render, an environment group sets it once). |
| Capistrano, own servers | The app's environment on each server, such as its systemd unit's `EnvironmentFile`, written over SSH with `$(deployangel token app)`, never typed out. |
| Started by a command on this machine, no host | Export it in whatever starts the app, read from the saved file at start: for example a small `bin/start` that runs `export DEPLOYANGEL_TOKEN="$(deployangel token app)"` and then the usual start command. The script holds no token, so it can be committed. |

A `.env` file only works if the app loads one (Rails, Django, and ASP.NET
Core don't on their own, without a gem such as dotenv or a package such as
python-dotenv).

Other hosts: https://www.deployangel.com/docs#platforms

## 5. Make sure the agent knows which release it's running

Most hosts need nothing: Kamal, Heroku (with the labs features above), Render,
Railway, Coolify, Dokku, Capistrano, ECS, and apps running from a git checkout
all name the release. A .NET app built in a git checkout carries its commit
too, in its assembly's version, except when a Docker build leaves `.git` out
of its context, as most `.dockerignore` files do. Without one, the agent uses
a fingerprint of the code, which works, but shows no commits or pull requests
on a release.

For Docker images and Fly.io, bake the commit in:

```bash
deployangel install docker      # adds ARG GIT_SHA / ENV DEPLOYANGEL_REVISION to the Dockerfile
docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .
fly deploy --build-arg GIT_SHA=$(git rev-parse HEAD)     # Fly.io
```

On GitHub Actions with `docker/build-push-action`, pass
`build-args: GIT_SHA=${{ github.sha }}`. Elastic Beanstalk and App Engine need
more: https://www.deployangel.com/docs#beanstalk

## 6. Put the verdict in CI (optional, recommended)

DeployAngel notices each new release when the agent reports it, so this is
optional. Registering from CI links each release to its CI run and starts
verification as soon as the deploy finishes, and the verify-release action
fails the deploy job when production rejects the release, so DeployAngel
becomes part of how the team ships.

- GitHub Actions: after the deploy step, add the action, and save the CI token
  as a repository secret named `DEPLOYANGEL_API_TOKEN` (ask first):
  `deployangel token api | gh secret set DEPLOYANGEL_API_TOKEN`.

  ```yaml
  - uses: DeployAngel/verify-release@v1
    with:
      api-token: ${{ secrets.DEPLOYANGEL_API_TOKEN }}
  ```

  It waits about 15 minutes for the first check, which private repositories
  pay for in runner minutes. If the user would rather not, and GitHub is
  connected in DeployAngel (each verdict then shows on the commit as a
  check), add `wait: none` under `with:` to register without waiting.

- Kamal: `deployangel install kamal` writes a post-deploy hook. Where the
  setup code was redeemed, it uses the saved token; elsewhere, such as CI, it
  needs `DEPLOYANGEL_API_TOKEN`.
- Capistrano: add `require "deployangel/capistrano"` to the Capfile.
- Anywhere else: run `deployangel release` at the end of the deploy. It
  registers the current git commit, or pass `--commit="$GIT_SHA"`.

Heroku: the user connects Heroku in the app's Settings in DeployAngel instead.

Also suggest connecting GitHub, under Integrations in the app's Settings in
DeployAngel: the user installs DeployAngel's GitHub App themselves. Each
release's verdict then shows as a check on its commit.

## 7. Set up coding agents to check each deploy

```bash
deployangel install agents
```

It adds DeployAngel's MCP server for Claude Code, Cursor, and Codex, and
instructions to `AGENTS.md` (with a `CLAUDE.md` that imports it) telling
agents to wait for the verdict after each deploy. These files are safe to
commit: they hold no token. In this checkout, the MCP server uses the token
saved by `deployangel setup`. Teammates redeem their own code, or set
`DEPLOYANGEL_API_TOKEN`, for example in an `.envrc` (direnv) that git ignores.

## 8. Deploy, then check

Ask the user to deploy as usual (or deploy if they ask you to). Once it's
live, run:

```bash
deployangel doctor --format=text
```

(Without `--format=text`, it prints JSON when it isn't run in a terminal.)
If the user starts or deploys the app themselves, give them the exact
command, and run `doctor` once they say it's running. Until then, "The
agent hasn't reported yet" is expected: report that, and that `doctor`
should show the processes reporting about a minute after it starts.

It checks the setup and what DeployAngel has seen: which processes report,
the release each runs, and any problem, with how to fix it. Fix what it
reports and run it again until it's clean.

Expect this on day one: for an app's first 24 hours of telemetry,
DeployAngel learns what's normal. Deploys then are checked for failures but
can't be cleared; the first deploy after that can be. That's normal, not a
problem to fix.

## 9. Tell the user what you did

Summarize:

- the files you changed, and whether they're committed;
- where each token went (by name, never its value), and anything they still
  have to do themselves (for example, pasting the app token into a host's
  dashboard from their own terminal);
- the result of `deployangel doctor`;
- that the first verdict can arrive after the 24-hour warm-up, on the next
  deploy;
- that meanwhile they can run a **fire drill** from the app's page in
  DeployAngel, about an hour after the agent first reports: a staged failed
  release on their own traffic, with the verdict, alert, and investigation a
  real failure gets. Nothing is deployed and no traffic is sent to the app.
  Recommend it: seeing a failure once is what makes the green verdicts
  believable.
