Skip to main content
A Procedure is a workflow primitive that does a well-defined unit of work in code, not in a prompt. It declares a typed input schema, a typed output schema, a closed set of error codes, and the capabilities it needs. The platform packages it into a pinned sandbox image, executes it on demand, and surfaces it to workflows as a graph node and to agents as a tool. Procedures are peers to agents in the workflow graph — same node-execution contract, same input/output validation, same governance pipeline. The difference is what runs inside: a procedure is deterministic-by-default code; an agent is a model turn. Picking the right primitive is the single most consequential design decision in a workflow graph. Spec: 2026-05-18-procedures-and-llm-routing-design.md.

When to reach for a procedure (and when not to)

When to reach for something else: if the work is a single API call with no looping, branching, or transformation, register it as a capability operation, not a procedure. Procedures earn their weight when there’s logic between the call and the result.

The three things a procedure declares

Every procedure is a directory at procedures/<id>/ with a forge.yaml manifest and an entrypoint (procedure.py or procedure.ts). The manifest binds three things to the procedure’s identity:

1. A typed I/O contract

Inputs and outputs are declared once and enforced at every boundary:
  • The workflow orchestrator type-checks upstream bindings against the input schema before spawning the sandbox.
  • The sandbox SDK exposes the input as a typed object — Pydantic for Python, Zod for Node.
  • The executor validates the procedure’s return value against the output schema before persisting stepResults.
A schema mismatch fails fast with SCHEMA_MISMATCH. There is no path for malformed output to reach a downstream node.

2. A closed set of error codes

Procedures fail through a fixed vocabulary of 16 codes. Eleven apply to every run:
Five more apply to long-running (detached) runs, which Forge watches after the dispatch returns:
SANDBOX_LOST means the sandbox died mid-run, LEASE_EXPIRED means Forge could not renew the run’s lease, POLLER_LOST means the backstop closed a run nothing else closed, BUDGET_EXCEEDED means the run’s compute time used up a budget, and CANCELLED means the workflow run that owns it was cancelled while it ran. Routers branch on these codes. The SDK and the executor share the same vocabulary, so authors program against a stable failure surface rather than parsing free-text. This is why a router-on-error node downstream of a procedure can be a normal router node — the conditions it branches on are typed.

3. The capabilities it needs

A procedure declares which capability domains it touches (linear, salesforce, secrets, etc.) from the capability domain catalog. The sandbox VM has no direct external egress by default — every capability call flows through Convex via a per-dispatch session token. The platform resolves the active provider for the domain, applies governance, runs the call, and returns the result. The sandbox never sees vendor credentials. This is what makes procedures portable. A linear-paginate-issues procedure runs against whichever Linear provider is registered for the workspace at dispatch time — the procedure code does not know or care.

Pinned image digests

Each procedure ships with a sandbox.image reference and (after CI builds it) a pinned imageDigest. The digest is the load-bearing identity for reproducibility: when a workflow run executes a procedure, the platform spawns the exact image digest pinned at registration time. Authors do not get to update a running workflow’s behavior by editing a base image out from under it. Image rebuilds are a registration event. Authors submit a PR that changes the manifest; CI builds the image, writes back the digest, and the next version of the procedure ships with the new digest pinned in the row.

Two surfaces: graph node and agent tool

A procedure’s exposedAs block declares which surfaces it appears on:
Both surfaces share the same image digest, the same schema, the same capability set, the same governance gates. A procedure is one thing exposed two ways. When the same workflow has a linear-paginate-issues graph node and a downstream agent that also wants to paginate, both call into the same pinned implementation.

The agent-tool surface is a two-key opt-in

agentTool: true is necessary but not sufficient. An agent only sees a procedure as a callable tool when both keys are set:
  1. The procedure opts in — exposedAs.agentTool === true (above).
  2. The agent is granted it — an operator adds a procedure grant to the agent definition (the “Procedures” section of the agent editor). Grants are individual and revocable; a revoked grant stops the tool from projecting on the agent’s very next dispatch.
This keeps the flag from becoming a fleet-wide capability grant: flipping agentTool makes a procedure grantable, not granted. When both keys are set, the agent gets a procedure_<slug> tool that resolves the head approved version at dispatch, runs the full procedure governance pipeline (recorded on the audit trail as the agent_tool dispatch surface), and executes in the same pinned sandbox as the graph node. Only approved procedures project as agent tools — provisional ones are graph-node-only until reviewed. Procedure grants persist only the Procedure’s stable family identity, never a copied slug. Renaming a Procedure therefore preserves existing grants and deny rules while agent configuration, skill linkage, and grant-gap checks resolve and show the family’s current procedureId. During revocation, Forge resolves that stable identity before changing access; if identity resolution is unavailable, the request fails instead of reporting a successful revoke that left access active. Search uses that same stable family identity. Forge maintains one search document and one embedding per logical Procedure, so publishing a new version or renaming its slug does not create duplicate search candidates. Search results show the family’s current procedureId; quality evidence remains attached to the exact current version that produced the result. The graph node and the agent tool are the top two rungs of a determinism ladder — bare reasoning (L0), skill-guided reasoning (L1), agent-invoked procedure tools (L3), and zero-agent graph nodes (L4). Work enters agentic and settles at the cheapest rung that meets its quality bar. Idempotency and determinism are author-declared invariants that the orchestrator reads:
  • idempotent: true — the orchestrator may retry on transient failure.
  • deterministic: true — identical inputs guarantee identical outputs. Stronger than idempotent; a Linear paginator is idempotent (re-invoking is safe) but not deterministic (Linear state changes between runs).

Governance is shared, not bolted on

Procedure dispatches go through the same Trust Fabric pipeline as agent dispatches — preflight, identity, safety, budget, scope, autonomy, guardrails. The procedure-specific gate set adds two checks the agent pipeline doesn’t have:
  1. Capability allowlist. Every capability domain the procedure declares must be in the workspace’s allow list for the dispatching principal. A procedure declaring salesforce cannot execute under a principal that lacks salesforce access — even if the operator personally has access elsewhere.
  2. Egress allowlist. Direct external egress from the sandbox is the empty set by default. The author must explicitly enumerate hosts in sandbox.egressAllowlist. The capability proxy host is always reachable; nothing else is unless the manifest names it.

Procedure governance gates

Before a procedure’s sandbox starts, the dispatch passes the procedure gates in order. The first failure stops the dispatch with a block; a policy that requires approval produces a hold; a clean walk produces an allow. Every gate outcome is recorded on the decision.
  1. Preflight (procedurePreflight): the procedure resolves at the requested version, is active, and has an entrypoint that matches what the executor will load.
  2. Identity (procedureIdentity): the caller may invoke this procedure. A run started by a person carries that person’s worker, which must be active. A run with no person by design, started by a schedule, an inbound webhook or an API key, carries the published workflow version as its identity. A run that names a person who does not resolve to a worker is refused.
  3. Safety (procedureSafety): the procedure’s lifecycle, and its declared sandbox.timeoutSeconds against the platform timeout ceiling. Concurrency is recorded here but enforced earlier: an over-limit dispatch waits in the workflow’s procedure queue.
  4. Compute budget (procedureComputeBudget): declared sandbox compute-seconds against the applicable compute budgets (platform, workspace, team, worker and procedure). Procedure compute budgets are separate from agent token budgets.
  5. Capability scope (procedureCapabilityScope): see below.
  6. Policy (procedurePolicy): applicable policies. One that requires approval turns the decision into a hold.
  7. Scope (procedureScope): role limits such as target environment, data access and write access.
  8. Autonomy (procedureAutonomy): whether the caller’s autonomy rung clears this action.
Procedures have no chat-response gate, because they do not return chat messages, and no verdict-schema gate: judges run on procedures, not as procedures. Decisions recorded before the current gate names may use an older name, such as preflight or capability_scope; the Trust Fabric explanation reads both.

Capability scope

A procedure’s capability surface is fixed by its manifest, so the gate checks the declared capabilities against the caller’s effective capability scope once, at gate time:
  • Deny list first. If any requested capability is on the caller’s deny list, the gate fails with capability_denied and names it.
  • Then the allow list. When the caller has a non-empty allow list, every requested capability must be on it, or the gate fails with capability_not_in_allow_list.
  • No allow list, no narrowing. An absent or empty allow list is intentionally permissive; lock a caller down by giving its role an explicit allow list.
  • This gate never holds; only the policy gate does.
Per-call enforcement still happens at the capability proxy when the procedure runs. The gate checks that capabilities are allowed; the proxy invokes them under the caller’s identity. Both must hold.

Egress is enforced when the sandbox starts

There is no egress gate. The hosts a procedure declares in sandbox.egressAllowlist are recorded on the decision, and Forge enforces them when it provisions the sandbox:
  • Empty allowlist: no direct external egress. The sandbox can still reach the capability proxy, so a procedure that declares no external egress can still make capability calls.
  • Non-empty allowlist: the sandbox may reach those hosts, narrowed by any governance scope on the decision, plus the capability proxy.
  • Governance can only narrow. A host the manifest never declared is rejected even if a decision names it.
A procedure that declares the linear capability does not need linear.app in its egress list; the capability proxy handles that call. To restrict compute, use the compute budget; to restrict which capabilities procedures may touch, use a policy. The capability-scope gate is a structural check, not the place for product policy.

Execution duration and long-running procedures

A procedure’s declared sandbox.timeoutSeconds chooses one of two execution shapes automatically — there is no flag, and no per-procedure opt-in beyond declaring a longer timeout: Limits. The maximum declarable duration is a platform setting, procedureTimeoutCeilingSeconds, defaulting to 4 hours and hard-clamped to the Vercel plan maximum of 24 hours. Operators raise it in Trust Fabric settings; it can never authorize beyond 24h. Compute-seconds budgets are enforced both at dispatch (against the declared timeout) and mid-run — the poller withholds the next lease extension and kills the command when an applicable budget is exhausted, so an over-budget long run stops even if the kill API call fails. Fail-safe by construction. A detached run only lives while the poller actively extends its lease. If the poller (or Convex) is down longer than ~15 minutes, the VM self-terminates and the run is recorded as LEASE_EXPIRED (retryable) — unsupervised spend dies rather than accruing. Cancellation and kill-switch stops work the same way: by withholding extension. Failure taxonomy. Terminal detached failures carry a stable code, surfaced on the run-detail node card and (for validation) the Builder: Builder validation runs a procedure’s declared test cases inline inside one action, so validation caps each test at a 540s ceiling (~9 min, under the action wall): author test cases that complete quickly, even for a procedure that runs for hours in production with real inputs.

What you get for treating procedures as first-class

A workflow that decomposes well into procedures earns three properties an all-agent workflow does not:
  • Cost stability. Procedure invocations cost compute-seconds, not tokens. A workflow that runs once a minute and paginates 4,200 issues per run costs cents per day instead of dollars per hour.
  • Latency stability. The model-free path takes the time its code takes — not the time the model takes today.
  • Reproducibility. A pinned image digest plus deterministic code yields the same output for the same input, every time. This is what makes a procedure-heavy workflow auditable end-to-end.
The Workflow Architect is biased to propose procedures wherever the work admits a procedure shape — see Use the Workflow Architect for why “did the Architect miss a procedure opportunity?” is itself a Judge criterion.