# Instance Actors

> Managing instance actor orchestrations for PostgreSQL health monitoring. Use when debugging stale actors, restarting actors, or troubleshooting health check issues.

- Skill: `majiayu000/instance-actors` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/instance-actors`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/instance-actors/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/instance-actors

---


# Instance Actor Management

## Overview
Instance actors are detached Duroxide orchestrations that run continuously to monitor PostgreSQL instance health. They can become orphaned or stale.

## Actor Lifecycle

1. **Created**: When instance is created, `create_instance` orchestration spawns an actor
2. **Running**: Actor loops forever: check health → update CMS → timer → continue-as-new
3. **Cancelled**: When instance is deleted, actor is cancelled via `cancel_instance()`

## Detecting Problems

### Stale Actor (running but not working)
- `last_health_check` > 5 minutes old
- Actor may be stuck, timer broken, or worker not processing

### Missing Actor
- `instance_actor_orchestration_id` is NULL
- Or orchestration doesn't exist in duroxide state

### Zombie Actor (in DB but not processing)
- Status shows "Running" but no health updates
- Often caused by server crash or DB migration

## API Endpoints

```bash
# Start new actor
curl -X POST /api/instances/:name/actor/start

# Restart actor (cancel + start new)
curl -X POST /api/instances/:name/actor/restart

# Cancel actor
curl -X POST /api/instances/:name/actor/cancel
```

## Duroxide Client Usage

```rust
// Cancel an actor
client.cancel_instance(&actor_id, "User requested cancellation").await?;

// Check if actor exists
match client.get_instance_info(&actor_id).await {
    Ok(info) => println!("Status: {}", info.status),
    Err(_) => println!("Actor not found"),
}

// Start new actor (detached)
client.start_orchestration(
    &new_actor_id,
    orchestrations::INSTANCE_ACTOR,
    serde_json::to_string(&input)?,
).await?;
```

## Recovery Procedures

### Restart All Stale Actors
```sql
-- Find instances with stale health
SELECT user_name, k8s_name, last_health_check, instance_actor_orchestration_id
FROM toygres_cms.instances
WHERE state = 'running'
  AND (last_health_check IS NULL OR last_health_check < NOW() - INTERVAL '5 minutes');
```

Then use the UI or API to restart each actor.

### After Database Migration
If duroxide state wasn't migrated, all actors are orphaned:
1. List all running instances
2. For each, call `/api/instances/:name/actor/start`