orangeforge.ai Download

documentation

How Forge works

What to know before writing an agent: what an agent is, how it is versioned, where it runs and how it is billed.

In one sentence#

A Forge agent is a folder on your disk — deterministic code, prompts, an output schema, test cases. forge push turns it into an HTTPS endpoint served worldwide over SSE streaming. Nothing else to administer.

Forge is designed to be driven by a coding agent (Claude Code, Codex…) rather than typed by hand. forge init installs a *skill* that teaches your assistant every command and the iteration methodology. In practice you describe the intent, the assistant edits the files and runs the commands. See Driving Forge from a coding agent.

Why "a prompt plus tools" no longer holds#

The common definition of an agent — a system prompt and a list of tools — hits a ceiling fast. A production agent needs to *decide in code*: route by intent before calling the model, run two searches in parallel, enforce a non-negotiable business rule, rebuild an answer from verified data instead of trusting the model.

Forge starts from the opposite premise: an agent is code that orchestrates LLM calls. The agent.ts file is a real TypeScript module. It calls the model when it needs to, several times, with different tool sets at each step, and keeps control of everything else. That is what lets you guarantee properties a prompt alone never will — for instance that no fabricated reference can ever leave the agent, because the code only returns what it verified itself.

Anatomy of an agent#

agents/my-agent/
  agent.json          # runtime, model, maxSteps, tools
  agent.ts            # the agent's code (worker runtime)
  prompt.md           # system prompt
  prompts/*.md        # named prompts, one per phase
  output.schema.json  # JSON schema of the output
  golden/*.json       # test cases with their expectations

These files are the source of truth. Deployed state is never edited directly: you edit a file, push, and observe. forge pull goes the other way on a fresh machine, and forge diff tells you what diverges.

The working loop#

  1. Edit — one intent per change, not a rewrite every round.
  2. Push — forge push my-agent.
  3. Test — forge bench my-agent replays every golden case.
  4. Read the traces before touching the prompt — forge trace <runId> shows each LLM step, each tool call, its inputs and outputs, tokens and cost. Most failures come from a poorly described tool, not a poorly written prompt.
  5. Judge — forge verdict records PASS/FAIL per case, building a quality history.
  6. Publish — forge push --activate, only once the golden set is green.

Immutable versions#

Every push records a version: prompts, code, configuration, schema, plus a hash of the shared library (lib/) and the workspace git SHA. The timeline (forge versions) shows what changed in each version — prompt, code, lib, config or status.

A useful consequence: forge trace <runId> --version returns the complete state of the agent that produced that specific run. Behaviour observed in production remains traceable to an exact state of the code, months later. And forge pull <slug> --version <n> rewrites local files from a past version — that is the rollback.

Edge execution#

An agent with runtime: "worker" is deployed to its own Cloudflare worker, isolated from every other. The tool loop runs at the edge, close to the caller. Invocation is public:

POST https://agents.agent-forge.cc/<slug>/invoke
x-api-key: fak_…

The response is an SSE stream: a first event carries the runId, then raw model events (tool-call, tool-result, text-delta…), and finally {"type":"final","output":…}. Structured traces do not travel on that stream — read them in the UI or with forge trace.

Isolation between teams#

Each team is a sealed tenant. An agent slug is never global: the API key presented at invocation determines the tenant, and therefore which agent answers. Two teams can each own a music-advisor without seeing or disturbing one another.

An fak_… key grants access to every agent in the tenant. It belongs on your servers — never in browser code, where any visitor could read it.

Secrets#

API keys for your tools (a business API, a third-party service) live as secrets of the agent's worker, set with forge secret set. They are not in a database, not in a prompt, not in your git repository. The CLI never holds a Cloudflare token: deployment is relayed by the control plane.

Outbound calls go through a proxy that injects the right key at the last moment — so the agent's code never needs to know the model key.

Models and cost#

You choose the model per agent, and even per phase within an agent. Two modes:

  • BYOK — plug in your own Vercel AI Gateway or OpenRouter key (forge llm set). Your tokens are billed by your provider, with no markup from us, and Forge credit no longer applies.
  • Prepaid credit — use our keys and top up as you go (forge credit add). The real cost of every run is visible in the traces.

Web search and application connectors (Gmail, Notion, Slack… via Composio) are included, with a monthly quota on the free tier.

Going further#