AAgent Daemon
Documentation & Support

Agent Daemon Help Centre

Guides, architecture workflows, video demonstration, framework setup, and troubleshooting playbooks to keep your production Python services self-healing.

Full Video Walkthrough & Live Demo

Watch how Agent Daemon monitors a live Python app (Coffee Shop API), catches a real-world checkout bug deployed to Render, diagnoses the root cause, generates a verified fix PR, and auto-merges it without human intervention.

Watch on YouTube ↗ Ask Questions
Video Key Moments & Chapters
0:00 – 0:45 What Agent Daemon is & the autonomous on-call AI engineer mission.
0:45 – 1:15 Google sign-in & plans: Monthly (₹100), Yearly (₹1,000), or 1-day free trial.
1:15 – 2:00 Connecting a repository via GitHub PAT and zero-touch monitoring installer.
2:00 – 2:40 Live demo: production coffee shop API running with healthy payments.
2:40 – 3:15 Inducing a live checkout failure & deploying to Render. Error alerted immediately!
3:15 – 3:50 AI diagnosis: stack trace analyzed, culprit lines traced, and safe patch generated.
3:50 – 4:25 Fix pull request opened on GitHub & GitHub Actions CI test suite runs.
4:25 – 4:55 Autonomous auto-merge: checks pass, PR squashes into main, Render redeploys fixed app!
4:55 – 5:15 Incident post-mortem report, cause explanation, unified diff, & admin console.

Remediation Modes: How Much Autonomy Do You Want?

You control the degree of autonomy for each connected repository. Switch modes at any time on your project settings page:

Fully Autonomous

Automatic Mode (auto)

The complete self-healing loop shown in the demo video. When an incident occurs, Agent Daemon diagnoses the cause, writes a surgical patch, creates a branch, opens a PR, waits for your GitHub Actions CI tests to pass, and automatically squash-merges into your base branch. Requires a private repository.

Recommended Default

Pull Request Only (pr_only)

Human-in-the-loop remediation. Agent Daemon analyzes the failure, generates a syntax-validated patch, and opens a GitHub Pull Request with the unified diff and incident explanation. Merging is left to your developers. Ideal for production teams requiring manual review.

Triage & Observability

Report Only (report_only)

Non-intrusive error monitoring. Clusters repeated exceptions into incidents, explains the likely root cause and culprit commits, and suggests manual fix recommendations on your dashboard. Does not create branches or open pull requests.

Getting Started & GitHub Configuration

Step 1 How to generate a classic GitHub Personal Access Token (PAT)

Agent Daemon interacts with GitHub using a classic personal access token. Here is how to create one in 60 seconds:

  1. On github.com, click your profile avatar in the top right → Settings.
  2. In the left sidebar, scroll to the bottom and click Developer settings.
  3. Click Personal access tokens → Tokens (classic).
  4. Click Generate new token → Generate new token (classic).
  5. Set Note to Agent Daemon and choose an expiration duration (e.g. 90 days or no expiration).
  6. Check exactly two permission scopes:
    • repo — Full control of private repositories (to read source evidence, create fix branches, and open pull requests).
    • workflow — Update GitHub Action workflows (used to install automated test validation).
  7. Click Generate token at the bottom. Copy your token immediately — GitHub will not show it again.

Security note: Tokens are encrypted at rest with Fernet (AES-128-CBC + HMAC) using TOKEN_ENCRYPTION_KEY and are never logged or stored in plain text. You can revoke the token on GitHub at any time to cut off access.

Step 2 Connecting your repository & Zero-Touch Installer

Once you have access (via trial or plan), navigate to Projects → Connect repository:

  1. Enter the repository Owner / Name (e.g. my-org/backend-api).
  2. Select your base branch (e.g. main or leave empty for default).
  3. Choose your remediation mode (Automatic, Pull request, or Report only).
  4. Paste your classic GitHub token and click Connect project.

What the Zero-Touch Installer does automatically:

  • Opens a pull request that adds incident_agent_monitor.py (the lightweight client).
  • Inserts import incident_agent_monitor at the top of your app entry point (e.g. app.py, main.py, wsgi.py).
  • Creates incident_agent_config.json with your project's ingest URL and unique ingest key.
  • Adds .github/workflows/agent-daemon-tests.yml so PRs have test validation checks.
  • Auto-merges the PR if repository permissions allow, or provides a direct link to merge on GitHub.
Step 3 Repository Privacy & Public vs. Private Repos

Agent Daemon treats public and private repositories differently for strict security reasons:

  • Private repositories: Support all three modes (Automatic, Pull request, Report only). Your ingest key and source files remain confidential.
  • Public repositories: Automatically locked to Pull request only mode. Because ingest keys in public repositories are visible to anyone, auto-merge is prohibited to prevent malicious error injections from pushing unauthorized code into production. A human must always review and merge PRs in public repos.

Framework Setup & Manual Integration

If you prefer manual setup rather than the automated PR, or use custom entrypoints, simply drop incident_agent_monitor.py into your project root and add one line to your app:

Framework Flask, FastAPI, Django, & WSGI Integration

Flask (app.py or wsgi.py):

import incident_agent_monitor # noqa: F401 (Agent Daemon error monitoring) from flask import Flask app = Flask(__name__) @app.route("/") def index(): return "Hello Production"

FastAPI / Starlette / ASGI (main.py):

import incident_agent_monitor # Starts error hook & heartbeat thread from fastapi import FastAPI app = FastAPI() @app.get("/") def read_root(): return {"status": "ok"}

Django (wsgi.py or asgi.py):

import incident_agent_monitor # Place before get_wsgi_application() import os from django.core.wsgi import get_wsgi_application os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings") application = get_wsgi_application()
Config Configuration file: incident_agent_config.json

Place this file in the working directory of your app (the same folder where your Python command is executed):

{ "ingest_url": "https://incident-agent-portal.onrender.com/ingest", "ingest_key": "YOUR_PROJECT_INGEST_KEY" }

The client will automatically load this config, spawn a daemonized heartbeat thread that reports health every 5 minutes, and attach an uncaught exception hook (sys.excepthook) and root logging handler.

Troubleshooting Playbooks & Failure Modes

Direct solutions for common issues based on Agent Daemon's architecture and safety gates:

Issue 1 Project shows "Offline" / No Heartbeat Received

Symptom: The dashboard project badge says Offline or "Last check-in: Never / 3 hours ago".

Root Causes & Solutions:

  1. App has not restarted since monitoring was merged: Deploy or restart your application so the new import incident_agent_monitor line is executed.
  2. Free tier hosting is sleeping: Services on Render, Railway, or Fly.io free tiers sleep after 15 minutes without web requests. Once asleep, the background heartbeat stops. Send a request to your app or configure a free pinger (e.g. UptimeRobot) hitting your app's health route every 10 minutes.
  3. Missing incident_agent_config.json: Confirm that incident_agent_config.json is located in the working directory of your running Python process.
  4. Outbound network restriction: Verify that your hosting environment permits outbound HTTPS connections to https://incident-agent-portal.onrender.com.
Issue 2 GitHub Installation PR Fails (401 / 403 / 404)

Symptom: When connecting a repository or clicking "Install monitoring", the portal displays a GitHub API error.

Resolution by Error Code:

  • HTTP 401 Bad credentials: The GitHub Personal Access Token was entered with extra spaces, has expired, or was revoked on GitHub. Go to GitHub → Developer Settings → Tokens (classic), generate a fresh token with repo and workflow scopes, and click Update GitHub token on your project page.
  • HTTP 403 Forbidden: The token is missing the repo scope, or the repository belongs to an organization that requires SSO authorization for personal access tokens. Click "Configure SSO" next to the token in your GitHub settings to approve your organization.
  • HTTP 404 Not Found: GitHub cannot locate the repository or branch. Confirm that the owner/repository spelling is exact (case-sensitive) and that the default branch (e.g. main instead of master) exists.
Issue 3 Auto-Fix Skipped or Marked "Needs Human"

Symptom: An incident appears in the dashboard, but its status changes to needs_human without opening a fix pull request.

Why this happens (Built-in Safety Gates):

Agent Daemon will NEVER perform automated code changes unless all 5 safety gates pass:

  1. Category is not a code bug: If the failure is classified as a database outage, third-party API downtime, missing environment variable, or server out-of-memory, Agent Daemon refuses to alter source code.
  2. Confidence is not "high": If the AI diagnostic engine has any doubt about the root cause, it safely escalates to human review.
  3. Bug is already resolved: If the bug is no longer present in the latest commit on your base branch, the fix is skipped.
  4. Safety flag: The diagnostic LLM explicitly marked safe_to_auto_fix = False.
  5. Maximum attempts exceeded: Agent Daemon limits automated fixes to 2 attempts per incident to prevent endless loops.

Action: Click into the incident to read the full root cause analysis, timeline, and recommended manual fix.

Issue 4 Fix PR Opened on GitHub but Not Auto-Merging

Symptom: The fix branch and PR were created on GitHub, but status remains pending or failed on the portal.

Troubleshooting Checklist:

  • CI checks must pass: Auto-merge requires at least one completed GitHub Actions check with conclusion success. If tests failed in CI, Agent Daemon safely halts and leaves the PR open for inspection.
  • Branch protection rules: If your repository enforces required code reviews (e.g. "Require at least 1 approval before merging"), GitHub's API blocks automated merges. You can either authorize bot merges or merge manually with one click on GitHub.
  • Public repository restriction: As a strict security measure, public repositories never auto-merge.
  • Merge conflicts: If other commits were pushed to your base branch while CI was running, the PR will await human rebasing.
Issue 5 Errors Occurring in App Not Appearing on Dashboard

Symptom: You triggered an error in your application, but no incident was created on the dashboard.

Verification Steps:

  1. Is the exception caught? Bare try ... except: pass or try ... except Exception as e: print(e) blocks swallow errors before they reach sys.excepthook. Use logging.exception("Failed processing") to ship handled exceptions.
  2. Check Ingest Key: If you rotated your ingest key on the dashboard, make sure to update incident_agent_config.json with the new key.
  3. Test Ingestion directly via cURL: Run this in your terminal to verify network connectivity to the portal:
    curl -X POST https://incident-agent-portal.onrender.com/ingest -H "Content-Type: application/json" -H "X-Ingest-Key: YOUR_KEY" -d '{"message":"Test diagnostic error","traceback":"Traceback: line 42 ZeroDivisionError","service":"test"}'
    A successful response returns {"status":"accepted","incident_id":"..."}.
Issue 6 Render Free Tier Sleep & Background Worker

Symptom: Cold starts take 30-50 seconds or background tasks take longer to trigger on free tier.

Explanation: Render's free tier spins down web instances after 15 minutes of inactivity. When a new error occurs, the instance wakes up automatically, but ingestion may take 30 seconds for the first request.

Tip: You can set up a free uptime monitor (such as UptimeRobot, BetterStack, or cron-job.org) targeting https://incident-agent-portal.onrender.com/health every 10 minutes to keep the worker continuously warm.

Frequently Asked Questions

Does Agent Daemon run my proprietary code on its servers?

No. Agent Daemon only reads source code files as text evidence via GitHub API to diagnose problems and construct minimal AST-checked diffs. Customer code and test suites are never executed on Agent Daemon servers.

Can Agent Daemon accidentally break my database or infrastructure?

No. Auto-fix is strictly confined to Python source code bugs. Database migrations, credentials, environment variables, Docker configurations, and infrastructure errors are strictly escalated to human engineers with needs_human status.

Can I disconnect a project or revoke access?

Yes. You can pause monitoring or permanently delete a project from your dashboard with one click. To instantly revoke all permissions on GitHub, simply delete the Personal Access Token in your GitHub account.

How does the 1-day free trial work?

Every customer is eligible for one 1-day free trial. Submit a request on the Billing page, and the Agent Daemon team of engineers will approve it promptly, activating 24 hours of unrestricted autonomous incident response.

Still Need Help or Have a Complex Setup?

Our co-founders and support engineers are available to assist with custom frameworks, private VPCs, and enterprise on-call requirements.

Contact Support & Founders About Co-Founders GitHub Project