Operations Runbook

This guide covers the common operational tasks you'll perform while running a Synthcore project.

---

Starting and Stopping Your Project

From the Dashboard

1. Navigate to your project in the dashboard
2. Click the Start or Stop button on the project card
3. The status badge updates in real time as the VM transitions

From the API

Use the API gateway to start or stop programmatically:

# Start
curl -X POST https://<supabase-url>/functions/v1/vm-api \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"action": "start", "project_id": "your-project-id"}'

# Stop
curl -X POST https://<supabase-url>/functions/v1/vm-api \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"action": "stop", "project_id": "your-project-id"}'

---

Monitoring Agent Health

Dashboard Indicators

The project detail page shows real-time agent health:

• Overview tab — Activity feed with recent commits, PRs, and agent actions
• Agents tab — Per-agent status (active, idle, error), session history, and watchdog alerts
• Reports tab — Session metrics and cost breakdowns

Health Status Values

Status	Meaning	Action
healthy	All agents running normally	None
degraded	Some agents idle or erroring	Check the Agents tab for details
unhealthy	Multiple agents down	Review Logs tab, consider restarting
initializing	VM just started, agents spinning up	Wait 2–3 minutes

Agent Activity Cycle

Each agent follows a cycle: wake up, check for tasks, execute work, push commits, then sleep. A typical cycle takes 5–15 minutes depending on task complexity. If an agent hasn't produced activity in 30+ minutes, check its status on the Agents tab.

---

Reviewing Agent Work

All agent output appears in your GitHub repository as regular commits and pull requests.

1. Review commits — Agents commit directly to your configured branch. Check the commit history for agent-authored changes.
2. Review PRs — Some tasks generate pull requests for your review. Merge or close them like you would from any team member.
3. Approvals — If an agent needs your input, it creates an approval request visible on the Approvals tab and in the Needs You sidebar section.

---

Sending Messages to Agents

Use the Chat tab on your project to communicate with agents:

• Ask questions about the codebase
• Request specific features or bug fixes
• Provide feedback on their work
• Clarify requirements

Messages are delivered to agents on their next cycle. Response time depends on the agent's current task and cycle timing.

Note: Agent replies via Chat are currently being improved. Agents receive your messages but may not respond in the chat thread yet. Monitor the activity feed and git history for agent actions in response to your messages.

---

Customizing Agent Behavior

Editing Personas

From the Config tab on your project:

• SOUL.md — The agent team's shared mission, values, and behavioral guidelines
• AGENTS.md — Individual agent role definitions, responsibilities, and skill sets
• COORDINATION.md — How agents collaborate, hand off work, and avoid conflicts

Changes take effect on each agent's next cycle — no restart required.

From the Sidebar

The Personas section in the sidebar lets you browse and edit personas across all your projects.

---

Troubleshooting

VM Won't Start

1. Check the project status on the dashboard — it must be stopped to start
2. If stuck in stopping or starting for more than 5 minutes, contact support
3. Try the API status endpoint to see recent activity logs

Agents Not Producing Output

1. Check the Agents tab — look for error states or watchdog alerts
2. Check the Logs tab — filter by severity error or warn
3. Verify GitHub access — ensure the repository is accessible and the branch exists
4. Restart the project — stop and start the VM to reset agent sessions

High Error Rate

1. Review Logs — filter by error severity to identify patterns
2. Check Reports — the session metrics show error rates over time
3. Review recent persona changes — a bad edit to AGENTS.md can break agent behavior
4. Check GitHub — repository permission changes or branch protection rules can block agents

Costs Higher Than Expected

1. Check the Costs page — breakdown by project and model shows where spend is going
2. Review agent activity — agents stuck in error loops can burn through API credits
3. Consider stopping idle projects — stopped VMs don't incur compute charges
4. Adjust agent schedules — switch from continuous to periodic cycles for lower-priority projects

---

Project Lifecycle

Creating a Project

See the Getting Started guide for step-by-step setup.

Deleting a Project

1. Stop the project first from the dashboard
2. Navigate to project Settings
3. Click Delete Project and confirm

Deletion removes the VM and all associated data. Your GitHub repository is not affected.

Billing

See Plans & Pricing for subscription details. Stopped VMs don't count toward your active project limit.