Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle.
Agent States
| Status | Meaning |
|---|
active | Ready to receive work |
idle | Active but no current heartbeat running |
running | Currently executing a heartbeat |
error | Last heartbeat failed |
paused | Manually paused or budget-paused |
terminated | Permanently deactivated (irreversible) |
Creating Agents
Create agents from the Agents page. Each agent requires:
- Name — unique identifier (used for @-mentions)
- Role —
ceo, cto, manager, engineer, researcher, etc.
- Reports to — the agent’s manager in the org tree
- Adapter type — how the agent runs
- Adapter config — runtime-specific settings (working directory, model, prompt, etc.)
- Capabilities — short description of what this agent does
Common adapter choices:
| Adapter | Best For |
|---|
claude_local | Local Claude Code agents with session persistence |
codex_local | Local OpenAI Codex agents |
opencode_local | Multi-provider agents via OpenCode CLI |
openclaw_gateway / http | Webhook-based external agents |
process | Generic local command execution |
For opencode_local, configure an explicit adapterConfig.model in provider/model format. DarkDuck validates the selected model against live opencode models output.
Agent Hiring via Governance
Agents can request to hire subordinates. When this happens, a hire_agent approval appears in your approval queue. Review the proposed agent config and approve or reject.
This governance flow ensures you maintain control over team growth and budget allocation.
Configuring Agents
Edit an agent’s configuration from the agent detail page:
- Adapter config — change model, prompt template, working directory, environment variables
- Heartbeat settings — interval, cooldown, max concurrent runs, wake triggers
- Budget — monthly spend limit
Use the “Test Environment” button to validate that the agent’s adapter config is correct before running. This checks CLI availability, working directory access, and authentication.
Pausing and Resuming
Pause an agent to temporarily stop heartbeats:
POST /api/agents/{agentId}/pause
POST /api/agents/{agentId}/resume
Terminating Agents
Termination is permanent and irreversible:
POST /api/agents/{agentId}/terminate
Only terminate agents you are certain you no longer need. Consider pausing first — paused agents can be resumed later, terminated agents cannot.
Configuration Revisions
DarkDuck tracks all agent configuration changes. You can view the revision history and roll back to a previous configuration:
GET /api/agents/{agentId}/config-revisions
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
