Why a spine

Most plants do not lack software. They have an ERP for orders, spreadsheets for quality, a maintenance system nobody updates, and a SCADA screen in the control room. What they lack is a spine: one agreed way to name things, one place where data lives, one set of rules about who may see and change what, and one secure path between the plant floor and everything above it.

Without a spine, each new tool is another island. With one, each new tool is a module that plugs into data that is already named, already trusted and already protected. That is the whole idea of this academy: build the spine once, properly, then bolt on modules in days instead of months.

What this element covers

Element one is the reference for everything the spine touches. It is long because it is the one element every later module assumes you have read. It covers:

• Your platform and your accounts (chapter 1): what to create, in what order, who owns it, and what it costs.
• Intent and the operating rules (chapter 2): the decision the platform exists to make, and the rules that keep it safe.
• The data model (chapter 3): ISA-95, the Purdue levels and why the schema comes before any screen.
• The Unified Namespace (chapter 4), naming and aliasing (chapter 5) and the data fabric (chapter 6): how plant data becomes analytics-ready without custom integration.
• Ignition (chapter 7): the SCADA and industrial application platform most often used to build the namespace.
• Purdue, ISA/IEC 62443 and the industrial DMZ (chapter 8) and cybersecurity by design (chapter 9), including the IT and OT regulations a manufacturer must meet.
• AI in the architecture (chapter 10) and setting up a fleet of AI agents, with its costs in detail (chapter 11).
• Lessons learned (chapter 12) from building the CivOps platforms, then the final assessment (chapter 13).

How it is scored

Your LMS records each chapter you open, your knowledge-check answers and your assessment score. The element is complete when you have opened every chapter and taken the assessment, and passed when you score 80% or more. You can retake the assessment; your LMS keeps the attempts. If you close the window, you come back to the chapter you left.

Own it from day one

The most expensive mistake in plant software is not a bug. It is finding, three years in, that the code lives in a contractor's GitHub, the database is on a consultant's credit card, and the domain is registered to someone who left. Session 1 prevents that by making the company the owner of every account before anything is built.

The five accounts

The seven steps

1. Create the GitHub organisation

Sign in at github.com/organizations/plan with a company email, choose the free plan, and name the organisation after the company. Add a second owner straight away. Turn on Require two-factor authentication for every member at the organisation's security settings ^[1].

2. Create the repository and protect its main branch

Create one private repository for the platform. Then add a branch protection rule (or a ruleset) on main: changes arrive only by pull request, CI must pass, and nobody can force-push ^[2]. This one setting is what lets AI agents work safely later: they can propose anything, and nothing reaches main without passing tests and a person's review.

3. Create the Supabase project

At supabase.com/dashboard, create a project in the company's organisation, in the region nearest the plant. Store the database password in the company's password manager, never in a chat, an email or a file in the repository ^[3].

4. Create the Vercel project and link it

At vercel.com/new, import the repository. Every pull request now gets its own preview address, and every merge to main deploys ^[4].

5. Put the secrets where they belong

Database keys go into Vercel's environment variables and GitHub's Actions secrets, entered by a person on those sites. They never pass through a chat with an AI agent, never appear in a prompt and never get committed. If one ever does, rotate it the same day.

6. Deploy the empty platform

Merge a first pull request with a single page. It goes live at the project's address. Nothing about it is impressive, and that is the point: the pipeline works before there is anything to break.

7. A second person deploys

Someone else in the company, with their own login, makes a small change and merges it. If they can, the platform belongs to the company. If they cannot, find out why now, while it costs nothing.

One decision, written down

An intent statement fits on one line: who decides what, how often, from which data. For example: the shift supervisor decides, every hour, which line gets the next maintenance technician, from downtime by reason and open work orders. If you cannot write it, you are not ready to build.

The intent drives the schema (chapter 3), the names (chapter 5), the role matrix and access rules (chapter 9), and the screens. It also tells you what not to build: anything that does not serve a decision is a report, and reports come later.

The operating rules

Every CivOps platform follows a short list of rules. They come from mistakes made and fixed while building real platforms; chapter 12 tells some of those stories. The rules that matter most for the spine:

ISA-95 in one picture

ANSI/ISA-95, published internationally as IEC 62264, is the standard for integrating enterprise and control systems ^[1][2]. It defines an equipment hierarchy (enterprise, site, area, then work centres such as lines and work units such as cells), and the objects that move between business systems and the plant: material, equipment, personnel, process segments, schedules and performance.

You do not need to read all of ISA-95 to use it. You need three habits: name equipment by its place in the hierarchy, keep the hierarchy the same in every system, and model the things that move (orders, lots, results) as ISA-95 objects rather than inventing new ones.

The Purdue levels

The Purdue Enterprise Reference Architecture, developed at Purdue University by a consortium led by Theodore J. Williams and published around 1992 ^[3][5], splits a manufacturing enterprise into levels by function and by how fast each must respond ^[3]. ISA-95 adopted its levels: Level 0 is the physical process, Level 1 basic control, Level 2 supervisory control, Level 3 site operations, and Level 4 business planning. Security practice later added Level 5 for the enterprise network and Level 3.5 for the industrial DMZ ^[4].

Schema first

A screen is a view of the data. If the data model is wrong, every screen built on it carries the mistake, and fixing it means rebuilding them all. So the spine designs the tables first, from the intent statement and ISA-95: equipment, the events that happen to it (state changes, downtime, results), the orders it works on, and the people who act.

-- Equipment follows the ISA-95 hierarchy; every row knows its place.
create table equipment (
  id          bigint generated always as identity primary key,
  company_id  bigint not null references companies(id),
  parent_id   bigint references equipment(id),
  level       text not null check (level in ('enterprise','site','area','line','cell')),
  code        text not null,            -- 'press-02': lower case, used in the UNS path
  name        text not null,            -- 'Press 02'
  isa_tag     text,                     -- 'TIC-101' from the P&ID, if it has one
  unique (company_id, parent_id, code)
);
-- Events are appended, never edited: a correction is a new row.
create table equipment_events (
  id           bigint generated always as identity primary key,
  company_id   bigint not null,
  equipment_id bigint not null references equipment(id),
  at           timestamptz not null,
  kind         text not null check (kind in ('state','downtime','count','result')),
  value        jsonb not null,
  source       text not null            -- 'uns', 'operator', 'import'
);

The problem it solves

A plant with eight systems that each need data from the others has, at worst, 28 point-to-point interfaces, each with its own mapping, owner and failure mode. Twenty systems means 190. The Unified Namespace (UNS) replaces that mesh with a hub: each system connects once, publishes what it knows, and subscribes to what it needs ^[1].

Walker Reynolds, President of 4.0 Solutions, coined the term. His definition: a real-time single source of truth for data in an industrial or manufacturing environment, semantically organized like the business and built to be open ^[2]. The idea rests on older ones (the message bus, event-driven architecture) applied to the plant. In practice a UNS has four properties:

• Single source of truth for current state: the latest value of everything, in one place.
• Organised by the business: the tree follows the ISA-95 hierarchy, so the address of a value says where it is.
• Report by exception: values are published when they change, not polled.
• Open and lightweight: usually MQTT, an open standard, so any system can join.

MQTT in ten minutes

MQTT is a publish/subscribe protocol standardised by OASIS (version 5.0 in 2019) and as ISO/IEC 20922 (version 3.1.1) ^[3]. Clients connect to a broker. A publisher sends a message to a topic, such as acme/cleveland/press-shop/line-3/press-02/state. Subscribers receive messages for the topics they subscribe to, with + matching one level and # matching everything below.

Sparkplug B: state you can trust

Plain MQTT lets anyone publish anything to any topic in any format. Sparkplug B, an Eclipse Foundation specification (version 3.0, also ISO/IEC 20237:2023), adds a fixed topic structure, a compact Protobuf payload, and above all state awareness ^[4][5]. When an edge node connects it publishes a birth certificate (NBIRTH, then DBIRTH per device) listing every metric and its current value. After that it sends only changes. If it drops, the broker publishes its death certificate, and every consumer knows the data is stale.

spBv1.0/{group_id}/{message_type}/{edge_node_id}/{device_id}

spBv1.0/cleveland/NBIRTH/line-3-edge
spBv1.0/cleveland/DDATA/line-3-edge/press-02
spBv1.0/STATE/scada-primary          <- the primary host says it is online

Most mature designs use both: Sparkplug B from the edge into Ignition (where state matters most), then Ignition or a DataOps layer republishes a readable ISA-95 tree for everyone else ^[6].

Brokers you can use

docker run -d --name uns -p 1883:1883 eclipse-mosquitto:2 mosquitto -c /mosquitto-no-auth.conf
docker exec uns mosquitto_pub -r -t acme/cleveland/press-shop/line-3/press-02/state -m RUNNING
docker exec uns mosquitto_sub -v -t 'acme/cleveland/#' -C 1

Four names for one motor

A single pump motor typically has four names, each for a different audience. The PLC programmer sees an address. The P&ID shows an ISA-5.1 tag. The electrical drawings use an ISO/IEC 81346 reference designation. Analytics and AI need a UNS path. None of them is wrong; the mistake is letting the wrong one escape into the wrong place.

ANSI/ISA-5.1-2024, Instrumentation and Control Symbols and Identification, gives instrument tags their grammar: the first letter is the measured variable, the following letters the function, then a loop number; FIC-101 is a flow indicating controller in loop 101 ^[1]. ISO/IEC 81346 describes any object from three aspects, each with its own prefix: function (=), product (-) and location (+) ^[2].

A naming rule you can enforce

1. Levels follow ISA-95, in a fixed order: enterprise, site, area, line, cell or equipment, then subsystem and signal.
2. Lower case, words joined by hyphens or underscores (pick one), no spaces, no punctuation that MQTT treats specially (+, #, / inside a level).
3. Units in the signal name (temp_c, pressure_bar, speed_rpm), so nobody guesses.
4. A reserved vocabulary for common signals: state, good_count, reject_count, ideal_rate, alarm. The same word means the same thing on every line.
5. Codes, not names, for levels (line2, not Second Packaging Line); the display name is an attribute.
6. No device addresses anywhere above Level 2.

# A CI check: every published topic must match the naming rule.
import re, sys
LEVEL = r"[a-z0-9]+(?:-[a-z0-9]+)*"
SIGNAL = r"[a-z0-9]+(?:_[a-z0-9]+)*"
RULE = re.compile(rf"^acme/{LEVEL}/{LEVEL}/{LEVEL}/{LEVEL}(?:/{LEVEL})*/{SIGNAL}$")
UNITS = ("_c", "_bar", "_rpm", "_kw", "_pct", "_count", "_s")
bad = []
for topic in open("topics.txt").read().split():
    if not RULE.match(topic): bad.append((topic, "pattern"))
    elif "temp" in topic and not topic.endswith(UNITS): bad.append((topic, "unit missing"))
for t, why in bad: print(f"{why:14} {t}")
sys.exit(1 if bad else 0)

Aliasing: one model, many devices

The plant will never have one PLC brand. Aliasing maps each device's address onto one clean model, so everything above the alias sees the same names whatever is underneath. There are three common places to do it:

• Ignition UDTs (user-defined types): a template such as Hydraulic Press with members, alarms, units and history settings. Each instance takes parameters that build the device path, so one template covers an Allen-Bradley press and a Siemens press ^[3].
• Sparkplug metric aliases: after the birth certificate names each metric, data messages carry a small number instead of the long name, which saves bandwidth on the wire ^[4].
• DataOps models (HighByte, Litmus and similar) that map many source tags onto one standard model and publish the result to the UNS ^[5].

Governance

What a data fabric is

Gartner defines a data fabric as a design concept that serves as an integrated layer of data and connecting processes, using metadata (much of it discovered automatically) to deliver integrated, reusable data across hybrid and multi-cloud environments ^[1]. In a plant that sounds abstract until you see the layers: sources at the bottom, connectivity (the UNS), a context and modelling layer, storage, and the uses at the top, all under one set of governance and security rules.

Industrial DataOps is the practice of building that context layer: model, contextualise and govern OT data once, then serve it to many consumers ^[2]. Products in this space include HighByte Intelligence Hub, Litmus Edge and Cognite Data Fusion; Ignition's UDTs and the UNS do part of the same job. Several now expose their models to AI agents through MCP servers ^[3][4].

Contextualisation

Context is everything an analyst would otherwise have to ask someone: the unit, the asset and its place in the hierarchy, the product or batch, the shift and operator, the limits. Add it at the edge or in the DataOps layer, publish it with the value, and nobody asks again.

Semantic models: build once, use on every line

A semantic model is a type. A Filler type might have state, good_count, reject_count, ideal_rate and speed. Every filler in every plant publishes that type, so an OEE screen built for one works for all, including the line you add next year. Standards help you avoid inventing types:

What analytics need

If the model carries those fields, these analytics exist the moment the data arrives. That is what analytics out of the box means: not a product feature, but a consequence of modelling first.

OEE, worked

OEE (overall equipment effectiveness) multiplies three ratios ^[5]. Availability is run time over planned time. Performance is ideal cycle time × total count over run time. Quality is good count over total count. In the shift above: availability = 433 ÷ 480 = 90%; performance = 395 ÷ 433 = 91%; quality = 383 ÷ 395 = 97%; OEE = 383 ÷ 480 = 79.8%.

Architecture

Ignition, from Inductive Automation, runs as a gateway: a server application you reach in a browser. Engineers build in the Designer; operators use Perspective (web and mobile) or Vision (desktop) screens. Tags come from tag providers fed by device drivers or OPC UA, and are organised with UDTs. The historian stores values in SQL databases; the gateway network links gateways for remote tags, history and central administration; and gateways can run as a redundant pair ^[1].

Licensing is per server and per module, not per tag, screen or client. That is why many mid-size plants choose it: adding the hundredth screen or the fiftieth operator costs nothing more.

What changed recently

Where it sits in Purdue

Joining the UNS: the MQTT modules

Cirrus Link's modules connect Ignition to MQTT ^[5]. MQTT Transmission publishes Ignition tags as Sparkplug B (edge side). MQTT Engine subscribes and turns Sparkplug back into Ignition tags (central side). MQTT Distributor is a broker that runs inside Ignition. A typical pattern: Edge gateways publish with Transmission; the site gateway subscribes with Engine; a broker in the IDMZ receives a bridged copy for everyone else.

What it costs

Purdue as a security map

Chapter 3 used Purdue to organise data. Security uses the same levels to decide what may talk to what. Data flows up; commands flow down only where they must; and nothing crosses from the enterprise (Levels 4 and 5) into operations (Level 3 and below) except through the industrial DMZ at Level 3.5 ^[1].

ISA/IEC 62443 in one page

ISA/IEC 62443 (which began as ISA-99) is the series of standards for securing industrial automation and control systems ^[4]. The parts you will meet most:

Every zone gets a target security level (SL-T), chosen in the 62443-3-2 risk assessment for the attacker it must withstand. Products declare the level they are capable of (SL-C), and the built system is assessed at the level it achieves (SL-A) ^[5].

The security levels in this table are typical teaching choices; your real targets come from your own risk assessment.

The industrial DMZ

The core rule, from Rockwell and Cisco's Converged Plantwide Ethernet (CPwE) design guides: all traffic from either side terminates in the IDMZ. Nothing passes straight through, and control protocols such as EtherNet/IP stay inside the industrial zone ^[6]. NIST SP 800-82 Rev. 3 gives the same guidance for OT generally ^[7].

For the highest-consequence sites, a unidirectional gateway (data diode) replaces the outbound firewall path: the hardware physically cannot carry anything back into OT.

Which regulations reach you

Most plants are not directly regulated by every framework, but customers often are, and requirements flow down by contract: a defense prime needs CMMC from suppliers, a pharma customer needs Part 11, and an EU buyer of your machines needs Cyber Resilience Act vulnerability reporting from you.

# site.conf (port 1883): bridge outward only
listener 1883
allow_anonymous true          # lab only
connection dmz
address 127.0.0.1:1884
topic acme/# out 1

# dmz.conf (port 1884)
listener 1884
allow_anonymous true          # lab only

Learn from incidents

Zero trust, inside the zones

NIST SP 800-207 defines zero trust: no implicit trust from network location; every request is authenticated and authorised by policy ^[7]. In OT, zero trust does not replace zones and conduits; it adds identity and checks inside them. CISA's April 2026 guide adapts it for OT, favouring passive monitoring over active scanning that can upset fragile devices ^[8].

Threat modelling with STRIDE

STRIDE, from Microsoft, is a checklist of six threat types to apply to every data flow in a design: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service and Elevation of privilege ^[9]. Draw the flows (operator tablet to broker, broker to historian, AI agent to MCP server), ask the six questions of each, and record a control for every threat.

The role matrix becomes the access rules

The spine's role matrix lists each role (operator, supervisor, quality lead, manager, AI agent) against each table or topic, with read, write or none. It becomes database row-level security policies, broker topic permissions and API checks. The rule is default deny: a role has no access until the matrix grants it, so a forgotten entry fails closed.

-- Default deny: turn on row-level security, then grant only what the matrix says.
alter table equipment_events enable row level security;

-- Operators may add events for their own site, and read their site.
create policy operator_insert on equipment_events for insert
  with check (company_id = auth.company_id() and auth.role() = 'operator'
              and equipment_id in (select id from equipment where site_id = auth.site_id()));
create policy site_read on equipment_events for select
  using (company_id = auth.company_id() and auth.role() in ('operator','supervisor','manager'));

-- The AI agent's role reads only; it has no insert, update or delete policy at all.
create policy agent_read on equipment_events for select
  using (company_id = auth.company_id() and auth.role() = 'ai_agent');

# Mosquitto access control list: the AI agent reads the line, writes nothing.
user ignition-edge-l3
topic write acme/cleveland/press-shop/line-3/#

user historian
topic read acme/#

user ai-agent
topic read acme/cleveland/press-shop/line-3/#

AI agents: the new boundary-crosser

An agent that reads a work order containing hidden instructions (prompt injection) and also has write access to tags is an incident waiting to happen. The OWASP Top 10 for LLM Applications (2025) names the risks ^[10]:

For governance, the NIST AI Risk Management Framework (Govern, Map, Measure, Manage) and its Generative AI Profile (NIST AI 600-1) give the programme structure; ISO/IEC 42001 makes it certifiable; and MITRE ATLAS catalogues real attacks on AI systems the way ATT&CK does for networks ^[11][12][13]. OWASP's general Top 10:2025 added Software Supply Chain Failures as a category, which applies to every dependency an agent installs ^[14].

Research-grade practice

• Assume breach, rehearse recovery: restore the database and a gateway from backup on a schedule, timed, and write the time down.
• Software bill of materials (SBOM) for what you ship and what you install; the CRA will effectively require one for products sold in the EU ^[15].
• Secrets in a vault, rotated, never in code, environment files committed to Git, chats or prompts ^[16].
• Red-team the agents: keep a library of injection prompts and run them in CI against every agent change, the same way you run unit tests.
• Post-quantum readiness: NIST published its first post-quantum standards (FIPS 203, 204 and 205) in August 2024; inventory where long-lived data and device certificates rely on today's public-key algorithms ^[17].

What the industry is doing

The pattern across all of them: agents that propose, models you choose, MCP for access to plant data, and people approving every change.

The options

(a) Open-weight models in the DMZ or at Level 3

Open-weight models are downloaded and run on your own hardware. Families in October 2026 include OpenAI's gpt-oss (20B and 120B, Apache 2.0, August 2025), Qwen, DeepSeek, Mistral, Google's Gemma and Meta's Llama; rankings change monthly, so check current benchmarks before choosing ^[7][8]. They are served with Ollama (easiest), llama.cpp (portable), vLLM (high throughput for many users or agents) or NVIDIA NIM (packaged containers) ^[9][10][11].

(b) Frontier models in the cloud

Frontier models (Anthropic's Claude, OpenAI's GPT, Google's Gemini) give the strongest reasoning and coding, with no hardware. They are reached directly or through a cloud provider: Claude, for example, is also offered on Amazon Bedrock, Google Cloud Vertex AI and Microsoft Foundry, which lets a company keep AI spending and data terms inside an existing cloud agreement ^[14]. Commercial API terms generally exclude training on customer content, and retention terms (including zero-data-retention agreements) vary by provider, model and contract; read the current page before you send plant data ^[15].

Source: Anthropic's pricing page, checked 3 October 2026 ^[16]. The Batch API halves prices for work that can wait; US-only inference costs 1.1×. OpenAI and Google publish comparable tiers on their own pricing pages.

(c) Hybrid: the 2026 mainstream

A local model handles real-time, data-in-place work (classify an alarm, summarise a shift from the UNS). A cloud model handles heavy reasoning on aggregates (root cause across weeks, writing code). A read-only MCP server gives either model access to modelled plant data, and an AI gateway in the IDMZ redacts, logs and limits everything that leaves.

MCP (the Model Context Protocol) is an open standard for connecting AI models to tools and data. Anthropic donated it to the Linux Foundation's Agentic AI Foundation in December 2025, so it is now under neutral governance ^[17]. An MCP server in the IDMZ that exposes only read tools (get_topic_value, query_history) is the safest way to let any model answer questions about the plant.

// A read-only MCP server: one tool, which reads the current value of a UNS topic.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import mqtt from "mqtt";
import { z } from "zod";

const values = new Map();
const client = mqtt.connect("mqtt://localhost:1883", { username: "ai-agent" }); // the broker ACL allows read only
client.on("connect", () => client.subscribe("acme/#"));
client.on("message", (topic, msg) => values.set(topic, msg.toString()));

const server = new McpServer({ name: "uns-reader", version: "1.0.0" });
server.tool("get_topic_value", { path: z.string().regex(/^acme\/[a-z0-9/_-]+$/) }, async ({ path }) => ({
  content: [{ type: "text", text: values.has(path) ? `${path} = ${values.get(path)}` : `No value for ${path}` }],
}));
// There is deliberately no write tool. Writes go through a person, not the model.
await server.connect(new StdioServerTransport());

On the horizon

How a fleet works

One orchestrator agent (or a person) splits the work into tasks and writes each worker a brief with acceptance checks: what to build, which files it owns, and the tests that prove it is done. Each worker runs in its own copy of the repository, on its own branch, with its own database and ports, and delivers a pull request. CI is the referee: nothing merges unless the tests pass from a fresh clone. A person reviews and merges.

Tools, for any model

Setting it up, step by step

1. Protect main (chapter 1): pull requests only, CI required. This is what makes agent work safe.
2. Make CI trustworthy: it runs every test from a fresh clone, on every pull request, on every database engine you support.
3. Give each worker a separate clone or git worktree and its own branch: git worktree add ../agent-3 -b feat/oee-page ^[1].
4. Give each worker its own database (its own role and database, or a disposable container) and its own port range (agent number × 100 + 3000).
5. Write briefs with acceptance checks the worker cannot change: the orchestrator owns the tests that define done.
6. Keep secrets out of every agent's reach: they live in the hosting platforms; agents get least-privilege tokens.
7. Set budgets: spend limits per workspace or key, a maximum per run, and alerts.
8. Commit and push small steps, so a restart loses minutes, not hours.
9. Merge in sequence: rebase each pull request on the latest main and let CI re-run before it merges.

# One worker's isolated workspace: its own folder, branch, database and ports.
N=3
git -C ~/platform worktree add ../agent-$N -b feat/agent-$N-oee-page
createdb -O agent_$N platform_agent_$N             # its own database, its own role
cat > ../agent-$N/.env.test <<EOF
DATABASE_URL=postgres://agent_$N@localhost:5432/platform_agent_$N
PORT=$((3000 + N * 100))
EOF
echo "Brief: build the OEE page. Done when npm test passes, including test/oee.test.mjs (do not edit it)."

What a fleet costs

Agent work is billed by tokens. Each agent works in a loop: read context, think, call a tool, read the result, repeat. Every request sends the conversation so far (the context) and receives a reply (the output). Four numbers decide the bill:

The cost of one request is: cached tokens × cache-read price + new tokens × cache-write price + output tokens × output price. Multiply by the number of requests. With prompt caching, the conversation's unchanged beginning is stored for a few minutes and re-read at a fraction of the price ^[2].

Worked example: eight agents, one night

Eight workers run for six hours; each makes 60 requests an hour, 2,880 requests in all. Each request carries 80,000 tokens of context (76,000 from cache, 4,000 newly written) and returns 1,500 tokens. An orchestrator on Opus 5.5 makes 120 larger requests. Prices are Anthropic's official list prices ^[3].

• Caching matters most. Keep the start of each conversation stable (instructions, then files) so the cache keeps hitting.
• On Opus 5.5, cheap cache reads make the frontier model only about 1.6× the cost of Sonnet 5.5 for agent loops, because most tokens are cache reads.
• Budget 20–30% more for retries and failed runs, plus CI minutes and any web searches ($10 per 1,000 on the Claude API).
• A sense check: Anthropic reports enterprise Claude Code use averaging about $13 per developer per active day; eight agent-nights at about $16 each is in line ^[4].
• Agent teams (agents that talk to each other) use roughly seven times the tokens of a single session; use them only when coordination pays for itself ^[4].

Try it: the fleet calculator

Change the assumptions and watch the night's cost. Prices are per million tokens.

Subscriptions, API, cloud or local

Subscription prices from claude.com/pricing; subscription limits are not published in tokens, so test with your own workload ^[5]. Other providers' plans (ChatGPT, GitHub Copilot, Cursor) follow similar patterns: a monthly allowance, then metered use.

Local, worked

Electricity at US averages of about 8.7¢ (industrial) to 14.5¢ (commercial) per kWh ^[6]. Local models also succeed less often on complex coding, which adds retries. Use local for privacy-critical and always-on light work; use the cloud for overnight builds.

Failure modes, and the controls

Messages: write first, then send

What the audit found. Before onboarding many businesses, an audit of email and texting found that a burst of messages could hit a provider's rate limit. Sent straight from the request, a refused message would simply be lost, and a retried one could arrive twice.

The fix. Every message is first written to an outbox row with a unique key, then sent with that key as the provider's idempotency key. Success marks it sent; a busy or network error schedules a retry with growing gaps; a refusal marks it failed at once. Daily jobs fan out through a queue instead of one long loop.

Isolation you can prove

What happened. A shared platform serves many businesses. One missing condition in one query could show one company another's data.

The fix. A database per business, with its own login that can reach nothing else; inside it, every table still carries the company id and a query without it throws. A test tries to cross the boundary on every change and must fail to.

Agents need walls

Tests that think like a reviewer

What happened. When this academy's question bank was generated, the correct answers bunched in one position, so a learner could pass by always picking the same letter. Separately, a homework assignment was due a week before the session that taught it.

The fix. Two tests: no answer position may hold 40% or more of the correct answers, and every assignment must be due after the session it depends on. When something slips through, add the test that would have caught it.

The rest of the twelve