Quickstart

Your First Verified Execution

Welcome to Forge.

This guide is intentionally different from a traditional API tutorial.

Rather than teaching individual endpoints, it walks through the complete lifecycle of a distributed execution—from submitting an execution contract to inspecting execution evidence and understanding replay.

By the end of this guide you will have independently verified how the Forge runtime behaves.

What You Will Accomplish

In the next few minutes you will:

create a project
generate an API key
execute a distributed workload
inspect the execution contract
understand deterministic execution
inspect execution evidence
verify replay compatibility
observe execution inside HQ

No previous Forge knowledge is required.

The Journey Ahead

Everything you do in this guide follows the same execution lifecycle used internally by the runtime.

text

Question
      │
      ▼
Execution Contract
      │
      ▼
Distributed Execution
      │
      ▼
Execution Evidence
      │
      ▼
Verification
      │
      ▼
Replay

Understanding this flow is far more important than memorizing API endpoints.

Before You Begin

Create an Organization and Project inside Forge HQ.

Projects provide isolation for:

execution history
API credentials
execution policies
billing
artifacts

Once the project has been created, generate an API key with compute permissions.

All execution requests require:

http

Authorization: Bearer <API_KEY>
Content-Type: application/json

Your API key represents execution authority for the project.

Submit Your First Execution

Every Forge workload begins with an immutable execution contract.

The execution contract defines:

what will execute
which primitive will execute it
which profile defines execution semantics
which inputs govern execution
which seed controls probabilistic behavior
which execution policy applies

The runtime treats this contract as the computational identity of the workload.

Execute the following request:

bash

curl -X POST https://api.forgepool.io/api/v0/ops/execute \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ctx": {
      "job_id": "quickstart-001",
      "trace_id": "trace-quickstart-001",
      "billing": {
        "mode": "test"
      }
    },
    "op": {
      "name": "mc",
      "version": 1,
      "profile": "insurance.v1"
    },
    "seed": {
      "mode": "explicit",
      "value": "ROOT_SEED_QUICKSTART"
    },
    "policy": {
      "target": "cpu",
      "min_agents": 1,
      "max_agents": 10,
      "verify": "none"
    },
    "args": {
      "iterations": 1000000,
      "claim_freq": 2.0,
      "claim_severity_mu": 6.0,
      "claim_severity_sig": 1.0,
      "cat_prob": 0.02,
      "cat_mu": 10.0,
      "cat_sig": 1.5,
      "policy_limit": 50000,
      "aggregate_limit": 250000
    }
  }'

You have now submitted your first execution contract.

What Just Happened

Although you issued a single API request, considerably more occurred inside the runtime.

Forge transformed your request into a deterministic distributed execution.

Conceptually, the runtime performed the following sequence:

text

Execution Contract
        │
        ▼
Deterministic Planning
        │
        ▼
Shard Construction
        │
        ▼
Distributed Execution
        │
        ▼
Verification
        │
        ▼
Deterministic Reduction
        │
        ▼
Execution Evidence
        │
        ▼
Replay Metadata

The returned result is only one artifact produced by this execution.

The execution itself is the durable object.

Inspect the Result

A simplified response may look similar to:

json

{
  "ok": true,
  "job_id": "01K...",
  "status": "COMPLETED",
  "hub": {
    "metrics": {
      "wall_ms": 1200,
      "agents_used": 4,
      "shards": 4
    },
    "output": {
      "loss": {
        "mean": 1853.4,
        "p50": 1200.2,
        "p95": 5400.8,
        "max": 21000.0
      }
    },
    "replay": {
      "root_seed": "ROOT_SEED_QUICKSTART"
    }
  }
}

Rather than focusing on the JSON itself, inspect what it represents.

You have received:

a job identifier
execution status
execution metrics
aggregated computational output
replay metadata

This information forms the beginning of the execution evidence preserved by Forge.

Verify Deterministic Execution

Execute the exact same request again without changing:

execution contract
primitive
profile
arguments
execution policy
root seed

The resulting computational distribution should remain consistent within the documented execution model.

You have now independently verified one of the central properties of the Forge runtime:

Deterministic execution is defined by execution semantics rather than infrastructure identity.

Learn more:

Deterministic Execution
Heterogeneous Execution

Inspect the Execution in HQ

Open Forge HQ and navigate to your execution.

Inspect:

execution contract
shard allocation
participating agents
execution timing
replay metadata
verification status
execution artifacts
billing information

HQ allows execution to remain inspectable after computation has completed.

This is where distributed execution becomes durable computational evidence.

What You Have Verified

At this point you have independently confirmed that Forge:

✓ accepts immutable execution contracts

✓ executes distributed workloads

✓ preserves deterministic execution semantics

✓ returns replay-compatible metadata

✓ records execution evidence

✓ separates execution from infrastructure

✓ allows execution to be inspected after completion

These properties form the foundation of the Forge execution model.

Execute Visually with Forge Studio

The same execution can also be composed graphically using Forge Studio.

Instead of constructing JSON requests, Studio allows you to compose execution systems visually while preserving identical execution semantics.

Whether execution originates from Studio, the public API, or an SDK, the underlying runtime remains identical.

Where to Go Next

Now that you have executed Forge, continue in the following order:

Core Concepts — understand execution contracts, primitives, profiles, and deterministic execution.
Trust Layer — understand verification, replay, heterogeneous execution, and execution evidence.
Architecture — understand how the runtime implements those guarantees.
Clients Guide — integrate Forge into production systems.
Providers Guide — contribute execution capacity.
Studio Guide — compose execution systems visually.

Each document expands one stage of the execution lifecycle you have already experienced.

Final Thought

Most distributed systems ask you to trust that execution happened correctly.

Forge asks something different.

Execute a workload.

Inspect the evidence.

Replay the execution.

Then decide for yourself.

That progression—from execution to independently verifiable computational evidence—is the foundation of the Forge execution system.

Quickstart ​

Your First Verified Execution ​

What You Will Accomplish ​

The Journey Ahead ​

Before You Begin ​

Submit Your First Execution ​

What Just Happened ​

Inspect the Result ​

Verify Deterministic Execution ​

Inspect the Execution in HQ ​

What You Have Verified ​

Execute Visually with Forge Studio ​

Where to Go Next ​

Final Thought ​