# Debugging on InsForge: CLI Diagnostics & Agent Troubleshooting

04 Apr 2026 • 3 minute

Junwen Feng

Engineer

Over the past three months, we've been closely following the issues developers share in our Discord community. We noticed a recurring pattern: many problems — slow queries, deployment failures, auth errors, mysterious 500s — could be diagnosed faster if developers (and their AI agents) had better visibility into what's happening on the backend.

So we built it. This post covers four new capabilities we've shipped to help you debug faster:

1. **Infrastructure observability API** — real-time EC2 instance metrics  
2. **Backend Advisor** — automated daily health scans  
3. **`diagnose` CLI command** — one-stop diagnostics from your terminal  
4. **`insforge-debug` skill** — agent-native troubleshooting for AI coding assistants

* * *

## 1\. Infrastructure Observability

Every InsForge project runs on a dedicated EC2 instance. Previously, you had no way to see what was happening at the infrastructure level — if your app slowed down, you were guessing.

Now, we expose real-time instance metrics through our API, and the CLI makes them accessible in one command:

```bash

```

This gives you:

- **CPU utilization** — is your instance compute-bound?  
- **Memory usage** — are you running out of RAM?  
- **Disk I/O** — is storage a bottleneck?  
- **Network throughput** — are you saturating bandwidth?

You can adjust the time range (`1h`, `6h`, `24h`) to spot trends. For example, if your app gets slow every day at 2pm, `--range 24h` will show you the pattern.

* * *

## 2\. Backend Advisor

We've added a Backend Advisor that automatically scans all active projects daily across three dimensions:

- **Security** — exposed credentials, missing RLS policies, permissive auth configs  
- **Performance** — unindexed queries, table bloat, connection pool pressure  
- **Health** — disk usage, service availability, configuration drift

Each scan produces actionable findings with severity levels (critical / warning / info), so you know what to fix first.

```json

```

Query advisor results from the CLI:

```bash

```

* * *

## 3\. The CLI Command

The new `diagnose` command brings all diagnostic capabilities together in one place:

```text

```

### Database Health Checks

Beyond metrics and advisor scans, `diagnose db` gives you real-time database health information:

```bash

```

This runs checks across multiple dimensions:

| Check | What it tells you |  
| --- | --- |  
| `connections` | Active/idle connections, pool utilization |  
| `slow-queries` | Currently running queries that exceed duration thresholds |  
| `bloat` | Table/index bloat from dead tuples |  
| `size` | Database and table sizes |  
| `index-usage` | Tables with low index hit rates (sequential scan heavy) |  
| `locks` | Blocked queries waiting on locks |  
| `cache-hit` | Buffer cache hit ratio (low = too many disk reads) |

You can run specific checks if you already know where to look:

```bash

```

### Aggregated Error Logs

`diagnose logs` pulls error-level logs from all backend sources into a single view:

```bash

```

Instead of checking `insforge.logs`, `postgREST.logs`, `postgres.logs`, and `function.logs` one by one, this command aggregates errors across all of them — useful when you don't know where the problem is.

* * *

## 4\. Agent-Powered Debugging with Skill

CLI commands are powerful, but an AI coding agent can do something humans find tedious: systematically work through a diagnostic checklist, cross-reference multiple log sources, and trace errors across the full stack — from the frontend SDK call all the way to the backend logs.

We've distilled the patterns from three months of community support into an **`insforge-debug` skill** that teaches AI agents how to diagnose InsForge projects. The skill covers 9 common scenarios:

| Scenario | When it triggers |  
| --- | --- |  
| SDK error objects | `{ data: null, error: { code, message } }` |  
| HTTP status anomalies | 400 / 401 / 403 / 404 / 429 / 500 |  
| Edge function failure | Runtime errors, timeouts |  
| Slow database queries | Query hangs, connection pool exhaustion |  
| Auth/authorization issues | Login fails, JWT expired, RLS denied |  
| Realtime channel problems | WebSocket disconnect, messages lost |  
| Backend performance degradation | High CPU/memory, all responses slow |  
| Edge function deploy failure | Deploy command fails |  
| Frontend deploy failure | Vercel build/deploy errors |

For each scenario, the skill tells the agent exactly which commands to run, in what order, and what information to look for. The agent doesn't need to guess — it follows a proven diagnostic path.

### Real-World Example

Here's a real case from yesterday. A developer hit this error while using the MiniMax M2.1 model:

> The AI provider returned an empty response. Verify the configured model is available.

The agent loaded `insforge-debug`, followed the diagnostic path, and traced the issue in under a minute:

```text

```

The agent went from error message to root cause — across frontend code, backend logs, and database config — without any manual guidance. This is what the `insforge-debug` skill enables: **the agent already knows the diagnostic playbook**.

* * *

## Getting Started

All of these features are available today. Use the latest CLI and try:

```bash

```

For AI-assisted debugging, the `insforge-debug` skill is published and ready to use. Point your agent at it, describe the problem, and let it run the diagnostic playbook.

We built these tools because debugging shouldn't require guesswork. Whether you're running commands yourself or letting an agent do it, the information is now there — logs, metrics, health checks, and advisor scans — all one command away.

If you run into issues or have feedback, drop by our [Discord community](https://discord.gg/DvBtaEc9Jz). The problems you share there are exactly what drives improvements like this one.