Getting Started for Developers

How IronWorks works under the hood: adapters, heartbeats, issues, and workspaces.

API Key Setup

IronWorks agents need LLM credentials to function. The platform supports two authentication methods:

Option 1: API Key (BYOK)

Store your provider's API key as a company secret. The key is encrypted with AES-256-GCM using a per-company master key.

# Store via the Secrets UI or API:
# Secret name: ANTHROPIC_API_KEY
# Secret value: sk-ant-api03-xxxxx...

# Or for OpenAI:
# Secret name: OPENAI_API_KEY
# Secret value: sk-xxxxx...

The credential resolution order is:

Company BYOK API key (secret named ANTHROPIC_API_KEY in company_secrets)
Company OAuth token (secret named ANTHROPIC_OAUTH_TOKEN)
Server-level process.env.ANTHROPIC_API_KEY (operator fallback for self-hosted)

Option 2: Anthropic OAuth

For Anthropic, you can use OAuth instead of a raw API key. Store the token as ANTHROPIC_OAUTH_TOKEN. The system sends it as a Authorization: Bearer header instead of x-api-key. OAuth tokens are useful when you want to use Anthropic's managed billing rather than prepaid API credits.

Adapter Configuration

Each agent has an adapter type that determines how it executes work. Available adapters:

Adapter	Description	Session Support
`claude_local`	Anthropic Claude CLI (Claude Code)	Yes
`codex_local`	OpenAI Codex CLI	Yes
`gemini_local`	Google Gemini CLI	Yes
`cursor`	Cursor editor agent	Yes
`opencode_local`	OpenCode CLI	Yes
`pi_local`	Pi CLI agent	Yes
`http`	Custom HTTP endpoint	No
`openclaw_gateway`	OpenClaw multi-agent gateway	No

Sessioned adapters maintain conversation context across heartbeats, which means an agent can pick up where it left off on a long-running task.

How the Heartbeat System Works

Agents don't run continuously. They operate on a heartbeat loop:

Poll — the server checks for agents with assigned work (issues in todo or in_progress status)
Wake — when an agent has work, the heartbeat service spawns an execution run
Execute — the agent's adapter is invoked with the issue context, workspace, and tools
Report — execution results are captured: cost, duration, output, status changes
Sleep — the agent returns to idle until the next heartbeat tick

The heartbeat runs at a configurable interval (default: 30 seconds). Concurrency is controlled per-agent — the default is 1 concurrent run, max is 10. This prevents an agent from being woken for a new task while it's still executing another.

// Agent data model (simplified)
{
  id: uuid,
  companyId: uuid,        // tenant isolation key
  name: "Senior Engineer",
  role: "engineer",       // determines default capabilities
  status: "idle",         // idle | working | paused | error
  adapterType: "claude_local",
  adapterConfig: {},      // adapter-specific settings
  budgetMonthlyCents: 0,  // per-agent budget (0 = company-level only)
  spentMonthlyCents: 0,   // current month spend
  reportsTo: uuid,        // org chart parent
  lastHeartbeatAt: timestamp
}

Issue Lifecycle

Issues are the unit of work in IronWorks. Here's the full lifecycle:

backlog → todo → in_progress → in_review → done
                    ↓                          ↓
                  blocked                  cancelled

Create — a human, the CEO agent, or a playbook step creates an issue with a title, description, priority (urgent/high/medium/low), and optionally assigns it to an agent
Assign — when an issue is assigned to an agent and its status is todo, the agent is eligible for wakeup on the next heartbeat
Execute — the heartbeat wakes the agent. The agent reads the issue, gets workspace access, and starts working. Status moves to in_progress
Complete — the agent marks the issue done. Cost data is recorded. The agent returns to idle.

Issues can have parent-child relationships (subtasks), be linked to a goal, belong to a project, and track which heartbeat run executed them.

// Issue data model (key fields)
{
  id: uuid,
  companyId: uuid,
  projectId: uuid | null,
  goalId: uuid | null,
  parentId: uuid | null,       // subtask relationship
  title: string,
  status: "backlog" | "todo" | "in_progress" | "in_review" | "blocked" | "done" | "cancelled",
  priority: "urgent" | "high" | "medium" | "low",
  assigneeAgentId: uuid | null,
  assigneeUserId: string | null,
  originKind: "manual" | "system" | "routine_execution" | ...,
  identifier: "STE-42",       // auto-generated
  executionRunId: uuid | null  // links to heartbeat_runs
}

Workspace Configuration

Each project can have workspaces — directories or repositories that agents work in. When an agent picks up an issue from a project, the heartbeat service:

Resolves the workspace directory (local path or managed git clone)
Sets up runtime services (if configured)
Passes the workspace as the working directory to the adapter
Cleans up execution artifacts after the run completes

For git-based projects, IronWorks can clone the repository into a managed workspace directory, scoped by company and project ID. The clone timeout is 10 minutes.

Custom Skills

Skills are shell scripts that extend what an agent can do. They are installed from skills.sh — a registry of agent skills. To add custom skills:

Navigate to the company Skills page
Browse the skills.sh catalog or add a custom skill URL
Assign skills to specific agents or all agents

Each role template comes with pre-assigned skills. For example, the CEO template includes ironworks (control plane interaction), ironworks-create-agent (hire new agents), and para-memory-files (persistent memory).

Budget Enforcement

The budget system operates at two levels:

Company level — monthly budget in cents, tracked in the companies table (budgetMonthlyCents, spentMonthlyCents). Default: $500/mo for API key customers.
Agent level — optional per-agent budget in cents, tracked in the agents table. Useful for limiting expensive agents.

Budget enforcement only runs for companies using llm_auth_method = "api_key". OAuth customers manage their own billing through Anthropic and are excluded from budget checks.

When the company hits 80% of budget, a high-priority issue is created and assigned to the CFO (or CEO if no CFO exists). At 100%, all non-CEO agents are paused with pauseReason: "budget_exceeded". This is deduped — only one alert per calendar month.