Forge Documentation

Getting Started

What is Forge?

Forge is an AI agent platform built on enterprise cloud infrastructure, deployable on AWS, Azure, or GCP. You define a team of specialist agents — a requirements analyst, a security architect, a financial modeller, a bid writer — and describe what you want them to produce. The agents execute in sequence, each one receiving the output of the last, and collectively they produce a structured set of deliverables.

Unlike a single AI chat session, Forge gives every agent a specific role, specific instructions, and access to real data from your company profile. The result is not a single response but a pipeline of specialist outputs that build on each other. A typical run might produce 6–12 documents, decisions, and recommendations in the time it would take to draft one email.

Navigating Forge

The left sidebar is organised into four groups so you can quickly find what you need:

Settings is further organised into four tab groups: Profile (Company Profile, Organisation), Billing & Usage (Billing, Impact Report, Usage), Integrations (API Keys, Webhooks, Secret Vault, MCP Servers), and Data (Knowledge Base, Data & Privacy).

Your first run

Running your first team takes about two minutes:

1. Go to Teams (Work group in the sidebar) and browse the 21 built-in templates. Each card shows the team mission and which agents are included.
2. Click "Use team" on the template you want. This takes you to the new run form with that team pre-selected.
3. Write a brief. The brief is your instructions to the team — what you want them to produce, for what context, and any specific constraints. A few sentences is enough to start.
4. Click Submit. Forge starts the first agent immediately. You will see a live timeline updating as each agent completes its work.

If this is your first time using Forge, the dashboard shows a 3-step onboarding checklist to guide you through setting up your company profile, running your first team, and exploring the output hub. Returning users see a collapsible getting-started checklist in the dashboard sidebar. Both can be dismissed once you are comfortable with the platform.

After your first run completes, check the This month card on the dashboard. It shows how many runs you have completed, an estimate of hours saved (based on the template used), and the EUR equivalent at typical consultant day rates. It updates in real time as runs finish.

Attach files to your brief

Briefs are multi-modal. On the new run form, use Attach to add a PDF, Word document, spreadsheet (CSV / Excel), or image (up to 10 MB each). Forge extracts the content and merges it into the brief so agents work from your actual documents:

• PDF / DOCX / TXT — full text is extracted.
• CSV / Excel — sheets are read into a readable table.
• Images (PNG/JPG/WebP) — a vision model describes the image and extracts any text, chart values, or diagram structure.

Attached files are stored with the run — they appear as downloadable chips on the run page so you always have the source documents.

Understanding statuses

Each run moves through a sequence of states. You can see the current status on the run page and in your run history.

Setting up your company profile

Go to Settings → Profile → Company Profile. This is one of the most impactful things you can do. Without a profile, agents guess your company name, capabilities, rates, and experience. With a complete profile, every run automatically uses your real data.

Fill in: company name (appears in all documents), tagline, core capabilities (what your company actually does), certifications (ISO 27001, Cyber Essentials, SOC 2, etc.), typical day rates (used in cost estimates), team summary, and reference projects. Save once. Every run from that point forward injects this context into every agent.

Teams and Agents

Built-in templates

Forge ships with 22 production-ready team templates. Each template has been designed with a specific mission, a curated set of agents in the correct execution order, and sensible defaults. You can use them as-is or clone them as a starting point for a custom team.

Available templates: DevSecOps Review, Bid Response, Business Plan, Investor Pitch, Board Report, Compliance Audit, Due Diligence, Marketing Campaign, Sales Intelligence, Content Strategy, Budget Planning, Research Report, Product Discovery, Vendor Evaluation, Process Improvement, Procurement Process, Technical Docs, Security Audit, Code Audit, Hiring Pack, Performance Review, Contract Review.

Building a custom team

Go to Teams → Create team. You will be asked for a team name and a mission statement. The mission is injected into every agent's context as a shared goal — write it clearly and specifically.

Pick agent roles from 100+ options. Roles include Market Researcher, Security Architect, Financial Analyst, Legal Reviewer, Persona Builder, Competitor Analyser, PRD Writer, and many more. Set the execution order — agents run sequentially, and each one receives the output of the previous agent as context.

Per-agent instructions

In the team edit page, click the pencil icon on any agent. This opens the instruction editor for that specific agent. Per-agent instructions override the agent's default behaviour and tell it exactly what to focus on for your use case.

Good instructions answer: what should this agent focus on? What data matters? What format should the output take? What should it ignore? Example instructions for a Market Researcher:

Focus on the European B2B SaaS market. Use EUR for all financial figures.
Prioritise data from the last 12 months. Include competitor pricing where
available. Identify the top 5 competitors with their market share estimates.
Reference any GDPR implications for data handling.

The team mission

The team Description field is not just metadata — it is injected into every agent's context as the team's shared mission. When you write a clear, specific mission, agents stay aligned with the goal even if individual briefs are short.

Example of a good mission: "Produce a comprehensive market entry analysis for a new geography, covering competitive landscape, market sizing, regulatory requirements, and a go-to-market strategy suitable for a Series A SaaS company."

Tools and Integrations

How tools work

Tools come in two types. Data tools (also called PRE-phase tools) run before the agent and inject results directly into the agent's context. The agent sees the fetched data alongside the run brief and uses it in its output. Available data tools: Web Search, Web Fetch, PDF Reader, HTTP GET.

Action tools (POST-phase) run after the agent and use the agent's output to take action in an external system. Available action tools: Slack Message, Jira Create Issue, Email, Webhook POST. Action tools support conditional firing so they only run when certain conditions are met.

Web search

Add a Web Search tool to any agent. Set the query using template variables so the search is tailored to each run. Results are automatically shown to the agent before it generates its output.

# Example query using template variables
{{agent.title}} competitor analysis Europe 2025

# Another example for a market researcher
{{agent.title}} market size TAM SAR SOM {{agent.output}}

Template variables

Use these variables in tool configuration fields:

Secret Vault

Go to Settings → Integrations → Secret Vault to store API keys, tokens, and passwords. Secrets are encrypted at rest and never exposed in the UI after creation. Reference them in any tool config field using {{secret.KEY_NAME}}. Never paste raw credentials into tool config fields.

Connecting Jira

Add a Jira tool to an agent (POST-phase). Required fields: base URL (your Atlassian domain), email ({{secret.JIRA_EMAIL}}), API token ({{secret.JIRA_TOKEN}}), project key. Set fire_condition to outcome == "completed" to only create tickets when the agent succeeds.

Connecting Slack

Add a Slack Message tool to any agent. Set the webhook URL using {{secret.SLACK_WEBHOOK}}. In the message template, use {{agent.output}} to include the agent's full findings. Use fire_condition to control when the message is sent.

# Example Slack message template
*{{agent.title}}*

{{agent.output}}

_Confidence: {{agent.confidence}} | Outcome: {{agent.outcome}}_

Workflow Automation

Run chaining

Run chains let the output of one team automatically trigger a new run on another team. Go to a team's tools page and scroll to Run Chains. Pick a target team, write a brief template using the previous run's data, and save. When this team's run completes, the next run starts automatically.

# Example chain brief: Market Analysis → Investor Pitch
Prepare an investor pitch based on this market analysis:

{{output}}

Focus on the market opportunity, competitive positioning, and
financial projections. Target audience: Series A investors.

Available chain variables: {{output}} (full output of the completed run), {{title}} (run title), {{brief}} (original brief). A common pipeline: Market Analysis → Investor Pitch → Board Report.

Inbound webhooks

Go to a team's tools page and enable the inbound webhook. Copy the unique URL. POST to it from any external system — GitHub, Jira, Zapier, Make, or a custom script — and a run starts automatically.

POST https://forge.shanova.se/api/webhooks/{team-webhook-id}
Content-Type: application/json

{
  "title": "PR #142 — Add OAuth2 support",
  "brief": "Review the security and architecture of this pull request...",
  "source": "github"
}

Conditional routing

Set a fire_condition on any action tool. The action only runs if the condition evaluates to true. Leave blank to always fire. Supported operators: ==, !=, >, >=, AND, OR.

# Only fire when high confidence
outcome == "completed" AND confidence >= 0.85

# Fire on success or when flagged for review
outcome == "completed" OR outcome == "blocked"

# Always fire (leave blank, or use)
outcome != ""

Approval gates

Mark any action tool as "Require approval". When the agent finishes, the action is held in a pending state. You will see a notification and a yellow panel on the run page asking you to approve or reject. Use this when you don't want AI outputs going to external systems without a human check — for example, before creating Jira tickets or sending Slack messages.

Scheduled runs

Go to Scheduled (Work group in the sidebar). Create a schedule: pick a team, write a brief template, and set a cron expression. Forge will fire the run automatically at the scheduled time. Useful for recurring reports — weekly market updates, monthly board summaries, daily risk digests.

# Common cron expressions
0 9 * * 1      # Every Monday at 9am
0 9 1 * *      # First of every month at 9am
0 9 * * 1-5    # Weekdays at 9am

Long-running & async runs

Runs don't have to finish in one sitting. A run can pause for hours, days, or weeks waiting for external data or a human decision, then resume automatically — its full state is saved between steps. This unlocks workflows like due diligence waiting on a data room or a tender waiting on clarifications.

• Wait for an external callback — an agent with thewait_for_callback tool pauses the run and generates a one-time URL. When an external system POSTs to it, the run resumes automatically and the payload is injected into the agent's context. Configurable expiry up to 30 days.
• Snooze / scheduled resume — on a paused run, choose Snooze (1h / 1d / 3d / 7d) and Forge auto-resumes it at that time.
• Resume now — resume any paused run immediately from the run page.

Paused runs show a Paused state in the runs list with the reason and the scheduled auto-resume time. Nothing is lost while a run waits — completed agents are kept and only the remaining agents run on resume.

Platform Features

Human checkpoints

Some agents may pause mid-run and ask a clarifying question. You will see an "Answer needed" notification and a yellow panel on the run page. Questions appear when an agent needs specific information it cannot infer from the brief — for example, a budget figure, a preferred vendor, or a binary go/no-go decision.

Answer each question and the run continues from where it left off. The run status shows as awaiting_input while waiting. If you don't answer, the run stays paused indefinitely.

Knowledge base

After each completed run, Forge automatically extracts key facts about your organisation from the outputs — company name, capabilities, market position, pricing signals, reference clients. These are stored in your knowledge base and injected into future runs automatically.

View and manage your knowledge base at Settings → Data → Knowledge Base. You can delete incorrect facts, edit entries, or add facts manually.

Projects

Projects let you group related runs together. Create a project in the Projects page, then create runs from within it. All project runs share context and appear together in one view. Useful for ongoing work — "Q1 market research", "Contract reviews for Client X", "Product launch planning".

Global search

Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) from any page in the dashboard to open the search modal. Type any word from a run title or brief and results appear as you type, showing each run's status, team name, and date. Use arrow keys to navigate, Enter to open a run, and Esc to dismiss. The search button in the sidebar nav and the mobile bottom bar also open the modal. Search is case-insensitive and matches across both run titles and brief content.

Notification bell

The bell icon in the left sidebar shows a live red badge when there are unread notifications. Forge creates a notification whenever a run completes, gets blocked, or needs your input at a human checkpoint. Click the bell to see the last 20 notifications. Clicking any notification navigates directly to that run and marks it as read. Use "Mark all read" to clear the badge at once. If you have enabled push notifications in Settings → Notifications, these events also arrive as push alerts.

Output annotations

On any completed run, each output card in the Output Hub has a small + button. Click it to expand an inline text area and type a private note — for example, "Send this section to legal for review" or "Numbers look off — check against Q3 report". Press Save. The note appears below the output as a quoted block. Notes are private: only you can see them. Delete any note with the × button. Use annotations to flag findings for follow-up, add context for handoffs, or mark sections that need human verification.

Usage insights

The dashboard This month card shows runs completed, hours saved (estimated per template type), and the EUR equivalent at typical consultant rates. It updates in real time as runs complete. For a fuller picture across all time periods, see the Analytics section in the dashboard which shows daily and monthly breakdowns, team usage, and recent failures.

Brief templates

Save any run brief as a named template. On the new run form, click a saved template to pre-fill the brief, team selection, and tone. Useful for recurring tasks where you run the same type of analysis on different subjects. You can also set the default tone per template.

Tone selector

Choose output style per run. Options: Formal (boardroom-ready language), Concise (tighter prose, less detail), Detailed (comprehensive coverage), Executive Summary (top-line findings only), Technical Deep-dive (full technical depth with specs). The tone setting affects all agents on that run.

Run comparison

On any completed run, click "Re-run" to start a new run with the same brief and team. After the new run completes, a "Compare with original" button appears. Click it for a side-by-side diff showing what changed between the two runs. Useful for understanding how a change to your brief or team configuration affected outputs.

Cancelling a run

You can stop a queued or running run before it finishes. Open the run page and click the Cancel run button in the sidebar. A confirmation step appears — click again to confirm. The run stops before the next agent starts and its status changes to cancelled. Any outputs already produced by completed agents are preserved in the Output Hub. You cannot cancel a run that has already completed or failed.

Agent performance analytics

The Analytics page now includes an Agent performance table at the bottom. For each agent role it shows how many runs that role has participated in, the average execution time, and the average confidence score. Use it to identify which agents take the longest, which consistently deliver high confidence, and where your pipelines spend the most time.

Self-improving teams

Every completed run is scored by an AI evaluator. On a team's page, the Self-improvement panel shows that team's rolling quality score, a trend (improving or declining), and a per-criterion breakdown that highlights the weakest dimension — completeness, accuracy, actionability, or clarity. Click Suggest an improvement and Forge analyses the lowest-scoring runs (and any low-star marketplace reviews) to propose a sharper system prompt for the single most impactful agent. You can A/B test the suggestion against the current prompt with an impartial judge, then Apply it — the previous prompt is kept so you can revert in one click.

Prefer hands-off? Flip on Autopilot in the same panel. A daily job then generates a suggestion for the weakest agent, A/B tests it, and auto-applies the winner when it beats the current prompt by a margin — leaving weaker ideas as suggestions for you to review. Every automatic change sends you a notification and can be reverted, so the team keeps getting better while you do nothing.

Steering a run live

While a run is still executing, a Steer the team box appears on the run page. Type a directive — for example "focus on EU compliance" or "keep it under two pages" — and Forge folds it into every agent that runs after it, at highest priority. The directive sticks for the rest of the run, so there's no need to cancel and start over. Each steer shows as queued until an agent picks it up, then applied, and is recorded in the run timeline.

Execution trace & trust check

Every finished run includes an Execution trace: a per-agent breakdown of how long each agent took, how many tokens it used (in and out), and its confidence — plus run totals for agents, tokens, and cost. Below it, the Trust check scans the run's outputs for potentially sensitive data (emails, phone numbers, card-like numbers, API keys, and tokens) and flags them with masked samples so you can review before sharing. It's non-destructive — nothing is altered — and a clean run gets an explicit "no sensitive data detected" badge. When something is flagged, a Copy redacted outputs button gives you a masked copy (each match replaced with [REDACTED:type]) without touching the stored output.

For the bigger picture, the Analytics page has a Quality & evaluation panel: your average quality score and its trend, the pass/warn/fail mix, a per-team quality ranking, and how many self-improvement suggestions were made, applied, and auto-applied over the selected period.

Marketplace, ratings & creator profiles

Publish a team to the Marketplace and others can clone it. Every published template can be rated 1–5 stars with a written review, and cards show the average rating, review count, and clone count. Claim a public handle under Settings → Creator Profile to get a shareable page at /creators/your-handle listing the teams you've published, and the marketplace's Top creators leaderboard ranks publishers by adoption.

Cost & Efficiency

Forge runs are significantly cheaper than the alternatives — both in token cost versus naive prompting and in time cost versus manual work. Here is how the numbers break down.

What does a Forge run cost?

A typical run consumes 150k–400k input tokens and 30k–80k output tokens. At GPT-4o pricing ($0.15/1M input, $0.60/1M output) this works out to €0.02–0.10 in token costs per run. Azure infrastructure (Container App + Function App) adds roughly €0.15–0.20 per run when amortised across all concurrent users. Total Forge cost: €0.20–0.35 per run.

Why is Forge more token-efficient than prompting?

A naive multi-prompt conversation accumulates context — each follow-up carries the full history, doubling or tripling token usage across a session. Forge avoids this with three mechanisms:

• Context routing — Each agent receives only the upstream outputs relevant to its role — not the entire run history. A commercial agent does not need the technical architecture; it receives only the requirements and solution design.
• Parallel execution — Independent agents run concurrently within a layer rather than sequentially, eliminating accumulated context between siblings.
• Structured JSON output — Agents return compact JSON rather than conversational prose. A requirements matrix as JSON is 60–70% smaller than the same information formatted as a paragraph.

Forge vs consulting: the ROI

The consulting equivalent value (hours a qualified professional would need) for each Forge template:

Token usage tracking

Forge records input_tokens and output_tokens for every completed run. You can see your personal ROI breakdown in Analytics → Cost vs Value. Platform admins see the full cost P&L (AI tokens + Azure infra + revenue margin) in the Admin → Costs dashboard.

Organisations & Billing

Every Forge account belongs to an organisation. When you sign up, a personal trial organisation is created automatically. Organisation admins can invite team members, manage seats, and upgrade the plan.

Plans: Trial (3 seats, 10 runs/month — free), Starter (10 seats, 100 runs/month — €29/mo), Pro (25 seats, 500 runs/month — €79/mo), Enterprise (custom). Plans are enforced at run creation and member invite time — you will see a clear error if a limit is reached.

Subscribing: Go to Settings → Billing & Usage → Billing, choose a plan, and complete checkout via Stripe. Your plan upgrades instantly once payment is confirmed. Use Manage Billing to view invoices, update your payment method, or cancel.

Inviting members: Org admins can invite by email from Settings → Profile → Organisation. New users receive a magic-link invite email and land on an acceptance page. Existing users are added directly.

API and Integration

Public REST API

Forge exposes a public REST API for creating runs and reading your run history. Base URL: https://forge.shanova.se/api/v1. All requests require an API key passed as a Bearer token. The full OpenAPI 3.0 spec is available at GET /api/v1/openapi.json. Try it interactively in the API reference →

# Create a run
POST https://forge.shanova.se/api/v1/runs
Authorization: Bearer {your_api_key}
Content-Type: application/json

{
  "team_id": "team_xyz",
  "title": "Market Entry Analysis — DACH",
  "brief": "Analyse the DACH B2B SaaS market..."
}

# List runs
GET https://forge.shanova.se/api/v1/runs
Authorization: Bearer {your_api_key}

# Query parameters: ?limit=20 ?status=completed ?team_id={id}

# Response
{
  "runs": [
    {
      "id": "run_abc123",
      "title": "Market Entry Analysis — DACH",
      "status": "completed",
      "team_id": "team_xyz",
      "created_at": "2026-01-15T09:00:00Z",
      "completed_at": "2026-01-15T09:08:42Z",
      "outputs_count": 8
    }
  ],
  "total": 142
}

API key setup

Go to Settings → Integrations → API Keys. Click "Create key". Give it a descriptive name (e.g. "Zapier integration" or "CI pipeline"). Copy the key — it is shown only once. If you lose it, you will need to rotate it. Keys can be revoked at any time from the API Keys settings page.

Consumer app keys (frg_app_…) are created from the Developer Portal — see below.

API key scopes (consumer apps)

Consumer-app keys carry action scopes that restrict what a key can do. This lets you issue a read-only key to one service and a write-capable key to another, without creating separate apps.

All scopes are granted by default. Restrict them from the app's edit modal in the Developer Portal. Calling an endpoint without the required scope returns 403 insufficient_scope. Org keys (frg_…) are not scope-restricted.

Usage API

Track token consumption and cost per app or per run programmatically. Useful for building usage dashboards for your own customers or reconciling AI spend.

# Aggregate usage — current calendar month (default)
GET /api/v1/usage
Authorization: Bearer frg_app_…

# Specify a custom period
GET /api/v1/usage?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z

# Response
{
  "period":        { "start": "2026-06-01T00:00:00.000Z", "end": "2026-06-30T23:59:59.999Z" },
  "run_count":     47,
  "input_tokens":  382000,
  "output_tokens": 91000,
  "cost_usd":      0.041800
}

# Per-run breakdown
GET /api/v1/usage/runs/{run_id}
# → { "run_id", "status", "model", "input_tokens", "output_tokens", "cost_usd",
#     "started_at", "completed_at", "duration_ms" }

Browser streaming and embed

Browser EventSource cannot send an Authorization header, so your frg_app_ secret key must never be embedded in client-side JavaScript. Instead, your backend mints a short-lived stream token and passes the stream_url to the browser.

// ── Backend (Node / edge function) ───────────────────────────────────
import { ForgeClient } from '@forge/sdk'
const forge = new ForgeClient({ apiKey: process.env.FORGE_APP_KEY! })

const run  = await forge.createRun({ team_id, title, brief })
const { stream_url } = await forge.createStreamToken(run.id)

// Send stream_url to the browser (e.g. in a JSON response)
return Response.json({ stream_url })

// ── Browser ────────────────────────────────────────────────────────
const src = new EventSource(stream_url)
src.addEventListener('event',  e => console.log(JSON.parse(e.data)))
src.addEventListener('status', e => console.log(JSON.parse(e.data)))
src.addEventListener('done',   e => { console.log('done'); src.close() })

Stream tokens expire after 15 minutes. Browser auto-reconnects reuse the same token. Reconnects also resume from the last received event automatically via theLast-Event-ID header — no events are replayed. If you need to pass a resume cursor manually, use the ?since=<sequence_number> query parameter.

Agent-as-Config — team manifests

Define a full agent team in JSON and deploy it programmatically via POST /api/v1/teams. The returned team_id works immediately in POST /api/v1/runs. No dashboard interaction required — suitable for CI/CD pipelines and code-first workflows.

POST /api/v1/teams
Authorization: Bearer frg_…
Content-Type: application/json

{
  "name": "Code Review Team",
  "description": "Automated security + quality review",
  "agents": [
    {
      "role": "reviewer",
      "system_prompt": "You are an expert code reviewer…",
      "tools": [
        {
          "tool_type": "web_search",
          "name": "Search language docs",
          "config": { "num_results": 5 }
        }
      ]
    },
    {
      "role": "security",
      "system_prompt": "You are a security engineer focusing on OWASP vulnerabilities."
    }
  ]
}

# Response 201
{
  "id": "e3a4f…",
  "name": "Code Review Team",
  "agent_count": 2,
  "created_at": "2026-06-09T10:00:00Z",
  "url": "https://forge.shanova.se/teams/e3a4f…"
}

Inbound webhook payload

Inbound webhooks accept a JSON body. The minimum required fields are title and brief. Any additional fields are stringified and appended to the brief automatically.

{
  "title": "string",    // Required. Used as the run title.
  "brief": "string",    // Required. Used as the run brief.
  "source": "string"    // Optional. Logged as the trigger source.
}

Outbound webhooks

Go to Settings → Integrations → Webhooks and add a URL. Forge will POST a JSON payload to that URL whenever a run completes, fails, is blocked, or is cancelled. You can register up to 10 webhooks per account and toggle each one on or off independently.

# Example payload
{
  "event":            "run.completed",
  "run_id":           "uuid",
  "run_title":        "Market Entry Analysis",
  "status":           "completed",
  "completed_agents": 8,
  "failed_agents":    0,
  "timestamp":        "2026-05-15T10:00:00Z"
}

Every delivery includes an X-Forge-Signature header. This is an HMAC-SHA256 signature of the raw request body using your webhook's signing secret. Verify it on your server to confirm the payload came from Forge and was not tampered with.

# Python verification example
import hmac, hashlib

def verify_forge_webhook(body_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

# Node.js / TypeScript
import { createHmac, timingSafeEqual } from "crypto"

function verifyForge(body: string, header: string, secret: string): boolean {
  const sig = createHmac("sha256", secret).update(body).digest("hex")
  return timingSafeEqual(Buffer.from(sig), Buffer.from(header.replace("sha256=", "")))
}

Your signing secret is shown in Settings → Integrations → Webhooks under each webhook entry (click "Reveal"). The delivery log shows the HTTP status code, response time, and any error for every attempt. Click "Replay" on any past delivery to resend it without waiting for the next run.

PWA install and push notifications

Forge works as a native app on mobile and desktop. On iOS Safari: tap the Share button, then "Add to Home Screen". On Android Chrome: tap the "Install app" button in the sidebar. On desktop Chrome or Edge: look for the install icon in the address bar.

Once installed as a PWA, go to Settings → Notifications and enable push. You will receive a push notification when: a run completes, a run is blocked and needs your approval, or an agent asks a clarifying question. Each notification links directly to the relevant run page.

Developer Portal

The Developer Portal at /developers is the self-serve hub for building products on top of Forge. Any logged-in user can create consumer apps, manage API key scopes, deploy teams from manifests, and monitor per-app usage — no admin access needed.

Creating a consumer app

Go to Build → Developers → New App. Enter a name and optionally a description. The frg_app_… API key is shown once — copy it immediately. Each account can create up to 3 consumer apps with a default quota of 100 runs/month each. Contact support to increase your quota.

Each app is fully isolated: separate key, separate run counter, and configurable scopes and team allowlists. Use one app per product or environment (e.g. "My Product – Production" and "My Product – Staging").

Managing an app

Click the app name in the Developer Portal to open its detail page. From there you can:

• See this month's run count, token usage, and cost at a glance.
• Rotate the API key — the old key stops working immediately.
• Edit scopes (e.g. remove runs:write for a read-only key).
• Restrict the app to specific team templates via the Allowed Teams picker.
• Delete the app and revoke its key permanently.

Deploying teams from the browser

Open the Deploy team from manifest panel on the Developer Portal page. Paste your JSON manifest into the editor and click Deploy team. The team ID is shown immediately and links to the team's edit page where you can verify agents and tools. This is the browser equivalent of POST /api/v1/teams — authenticated with your session, no API key needed in the editor.

Infrastructure as Code (forge iac)

Manage your teams declaratively from version control. Define them in a forge.yaml (or .json) manifest and reconcile with the Forge CLI — like Terraform, but for agent teams. Each team carries a stable key, so applies are idempotent and safe to run from CI.

# forge.yaml
version: 1
teams:
  - key: code-review
    name: Code Review Team
    description: Reviews pull requests for security and quality
    agents:
      - role: reviewer
        name: Senior Reviewer
        system_prompt: You are an expert code reviewer...
        tools:
          - tool_type: web_search
            name: Search docs
            config: { num_results: 5 }
      - role: security_auditor
        name: Security Auditor
        system_prompt: You audit code for OWASP Top 10 issues...
schedules:
  - key: nightly-review
    team: code-review          # references a team by its key
    title: Nightly review
    brief: Review the latest changes on main.
    cron: "0 2 * * *"

Then run the reconcile workflow:

forge iac export            # pull current teams into forge.yaml
forge iac plan              # preview: + create  ~ update  = no-change
forge iac apply            # reconcile (prompts before changing)
forge iac apply --prune    # also remove managed teams not in the file

plan shows a colour-coded diff and changes nothing; apply creates, updates, or (with --prune) destroys teams to match the manifest. Use --yes to skip the confirmation in automation. Teams, their agents, each agent's tools, and scheduled runs are all managed from the manifest —forge iac export pulls your existing configuration in, and apply reconciles it. A top-level schedules: list references each team by its key.

Interactive API reference

Browse and test every v1 endpoint live at /docs/api. The reference renders the OpenAPI 3.0 spec with authentication pre-wired — enter your key once and try any endpoint directly in the browser. It works without a Forge account, so you can share it with evaluating developers.

Memory API

The Memory API gives agents persistent context about your users and your product. Store facts once; they are automatically injected into every future run brief — no prompt engineering required.

import { ForgeClient } from '@forge/sdk'
const forge = new ForgeClient({ apiKey: process.env.FORGE_APP_KEY! })

// Store app-wide context — injected into every run
await forge.upsertMemory({
  key:       'company_name',
  content:   'Acme Corp — B2B SaaS for HR teams, 50 employees, Series A',
  namespace: 'global',
})

// Store per-user context — injected only when external_user_id matches
await forge.upsertMemory({
  key:              'role',
  content:          'Senior Product Manager at Acme, focus on enterprise accounts',
  namespace:        'profile',
  external_user_id: currentUserId,
})

// On next run with this user → agents automatically receive:
// [CONTEXT MEMORY]
// GLOBAL:
//   company name: Acme Corp — B2B SaaS for HR teams, 50 employees, Series A
// PROFILE:
//   role: Senior Product Manager at Acme, focus on enterprise accounts
const run = await forge.createRun({ team_id, title, brief, external_user_id: currentUserId })

// Search memory
const { entries } = await forge.listMemory({ namespace: 'profile', external_user_id: currentUserId, q: 'enterprise' })

// Delete when no longer needed
await forge.deleteMemory(entries[0].id)

Iframe embed

The embed URL is a hosted Forge page that shows a live run timeline — status badge, agent event feed, output cards, and usage meter. Drop it into an <iframe>in any framework; no npm install, no CSS setup.

// Backend — mint a stream token and get the embed URL
const { stream_token, embed_url } = await forge.createStreamToken(runId)
// Or: const embed_url = forge.getEmbedUrl(stream_token)

// Send embed_url to the browser
return Response.json({ embed_url })

// React
<iframe src={embed_url} width="100%" height="500"
        style={{ border: 'none', borderRadius: 12 }} />

// Plain HTML / Vue / Svelte / Angular
<iframe :src="embedUrl" width="100%" height="500" frameborder="0" />

The embed page authenticates via the frg_strm_… token in the URL — yourfrg_app_ secret key is never exposed to the browser. Tokens last 15 minutes. After the run completes, the embed shows all outputs and the final token usage.

TypeScript SDK

The @forge/sdk package is a zero-dependency TypeScript client for the Forge v1 REST API. It works in Node.js 18+, Deno, Bun, and modern browsers.

Installation

npm install @forge/sdk
# or
pnpm add @forge/sdk

Quick start

import { ForgeClient } from '@forge/sdk'

const forge = new ForgeClient({ apiKey: process.env.FORGE_API_KEY! })

// List teams
const { teams } = await forge.listTeams()
const team = teams.find(t => t.name === 'DevSecOps')!

// Create a run
const run = await forge.createRun({
  team_id: team.id,
  title:   'Q3 Security Audit',
  brief:   'Review our Node.js API for OWASP Top 10 vulnerabilities...',
})

// Stream events until done
for await (const frame of forge.streamRun(run.id)) {
  if (frame.type === 'event')  console.log(frame.data.agent_role, frame.data.title)
  if (frame.type === 'status') console.log(frame.data.completed_agents, '/', frame.data.total_agents)
  if (frame.type === 'done')   console.log('Finished:', frame.data.status)
}

// Pull structured outputs
const { outputs } = await forge.getRunOutputs(run.id)
for (const o of outputs) console.log(o.output_type, ':', o.title)

Methods

All methods return typed Promises. streamRun() returns anAsyncGenerator<StreamFrame> — use it with for await...of.

Error handling

import { ForgeClient, ForgeError } from '@forge/sdk'

try {
  await forge.createRun({ team_id: '...', title: '...', brief: '...' })
} catch (err) {
  if (err instanceof ForgeError) {
    console.error(err.message, err.statusCode, err.body)
    // statusCode 429 → quota exceeded
    // statusCode 403 → team not in consumer app allowlist
    // statusCode 409 → run already terminal (cancelRun)
  }
}

Consumer App keys

Consumer apps use frg_app_… keys instead of user keys. Pass your key the same way — the SDK detects the prefix automatically. Consumer app runs are metered (billed per run via Stripe Billing Meters).

const forge = new ForgeClient({
  apiKey: process.env.FORGE_APP_KEY!, // frg_app_…
})

// Attach your own user ID to the run for filtering / analytics
const run = await forge.createRun({
  team_id,
  title,
  brief,
  external_user_id: currentUserId,
})

Command-Line (CLI)

The @forge/cli tool brings Forge to your terminal — create runs, deploy teams, and manage memory without leaving the command line. It streams live agent events directly in your shell, making it ideal for development workflows and CI/CD pipelines.

Installation

npm install -g @forge/cli

# Authenticate (stores key in ~/.forge/config.json)
forge auth login

# Or use an environment variable (ideal for CI)
export FORGE_API_KEY=frg_...

Creating and streaming runs

forge run create streams live agent events in your terminal by default — you watch each agent start, think, and complete in real time, with a final summary of outputs, duration, and cost.

# Create a run and watch it live
forge run create --team <team-id> --title "Q3 Security Audit" \
  --brief "Review our Node.js API for OWASP Top 10 vulnerabilities"

# Create without streaming (prints the run ID and exits)
forge run create --team <team-id> --title "..." --brief "..." --no-follow

forge run list                 # recent runs
forge run logs <run-id>        # stream live events for an existing run
forge run outputs <run-id>     # list artifacts
forge run cancel <run-id>

Teams and memory

# Deploy a team from a JSON manifest (Agent-as-Config)
forge teams deploy ./my-team.json
forge teams list

# Manage persistent memory injected into future runs
forge memory set company_name "Acme Corp" --namespace global
forge memory set role "Senior PM" --namespace profile --user user-123
forge memory list --namespace profile --user user-123

CI/CD integration

Use the --json flag on any command for machine-readable output you can pipe tojq, and --no-follow to fire-and-forget runs from a pipeline.

# GitHub Actions — review every pull request
- run: npm install -g @forge/cli
- run: |
    forge run create \
      --team $TEAM_ID \
      --title "Review PR #${{ github.event.pull_request.number }}" \
      --brief "${{ github.event.pull_request.body }}" \
      --no-follow --json
  env:
    FORGE_API_KEY: ${{ secrets.FORGE_API_KEY }}

GitHub Actions

Run a Forge agent team on every pull request. The Forge AI Run action creates a run, streams agent events into the job log, posts the result as a sticky PR comment, and can fail the check as a quality gate. Perfect for automated DevSecOps reviews, code review, and compliance checks.

Quick start

Add your Forge API key as a repository secret named FORGE_API_KEY(Settings → Secrets and variables → Actions), then drop this workflow into.github/workflows/:

name: Forge PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write   # to post the result comment
      contents: read
    steps:
      - uses: ShanovaAI/Forge/packages/github-action@main
        with:
          api-key: ${{ secrets.FORGE_API_KEY }}
          team-id: <your-team-id>
          brief: |
            Review PR #${{ github.event.pull_request.number }}:
            ${{ github.event.pull_request.title }}
            ${{ github.event.pull_request.body }}
          fail-on: blocked,needs_revision

Quality gate

The fail-on input turns the action into a merge gate. The PR comment is still posted first, so reviewers always see why a check failed. Supported conditions (comma-separated):

Outputs

The action sets run-id, run-url, status,outputs (JSON), and cost-usd for use in later steps. Setwait: false to fire-and-forget, or comment: false to skip the PR comment.

Support

Forge has a built-in support centre at Support in the sidebar. It combines an AI assistant for instant answers with a human ticket system for anything more involved.

AI assistant

The AI assistant answers questions about using Forge — templates, custom teams, scheduled runs, integrations, billing, and more. Responses are streamed in real time. If the assistant cannot resolve your issue, click Still need help? Open a ticket to escalate with the conversation context automatically attached.

Support tickets

Click New Ticket to open a ticket directly. Choose a category (General, Billing, Technical, Account, or Feature request), write your subject and description, and submit. The Forge team will reply in-app — you will receive a notification when there is a new reply. You can add follow-up messages from the My Tickets tab.

Org admins see all tickets raised by anyone in their organisation under the Organisation Tickets tab and can reply on behalf of the team.