RunForge

Deploy & run

How to create a project, deploy from GitHub, trigger runs, and handle approvals.

Create a project

Go to Projects → New project. Choose GitHub as the source (or create without a repo for manual setup). If GitHub isn't connected yet, you'll be prompted to authorize; after that, select your repo and branch.

The platform fetches the branch and analyzes the repo (agent.yaml, requirements.txt, pyproject.toml) to suggest project name, entrypoint, and Python version. You can override any of these.

Config step

  • Project name — Shown in the dashboard. Pre-filled from agent.yaml if present.
  • Entrypoint — module:function (e.g. agent:run). The function must be registered with @app.agent("..."). Pre-filled from agent.yaml if present.
  • Browser — Enable if your agent uses Playwright (e.g. ctx.browser.new_page()). Off for tool-only agents.
  • Tools — Optionally enable and select which tools (Gmail, Google Calendar, Slack, etc.). You will connect your accounts in Settings → Tools after deploy.

Environment variables

Add any env vars your agent needs (e.g. API keys). Keys and values are stored encrypted. They are injected into the run environment when the worker executes your agent.

Deploy

Click Deploy. The platform:

  1. Clones your repo (branch you selected).
  2. Analyzes it (Python version, entrypoint, dependencies).
  3. Strips agent-runtime from requirements.txt and injects the SDK used by the platform.
  4. Builds a Docker image (with Playwright and browser deps if browser is enabled).
  5. Marks the deployment ready so runs can use it.
The build log streams in the UI (clone → analyze → build → start). If the build fails, fix the repo or config and redeploy from the project's Deployments tab.

Trigger a run

From the project Overview or Runs tab, click Trigger run. You can pass optional input JSON (e.g. {"recipient": "user@example.com"}). This payload is available to your agent as the input argument.

The run is pushed to a queue. A worker picks it up, starts a container with your image, and executes your entrypoint with RUN_ID and INPUT_PAYLOAD in the environment. You can watch the run on the run detail page: steps, logs, artifacts, and approval prompts.

Run lifecycle

A run moves through: Queued → Running → (optionally Waiting for approval) → Succeeded or Failed.

  • If the agent uses a commit step, the run pauses and an approval request is created. You approve or reject from Approvals or the run detail page. On approve, the agent continues; on reject, the run fails with ApprovalRejectedError.
  • Steps and logs are reported to the platform in real time. Artifacts (files saved via ctx.artifact) appear in the run detail.
Approval timeout: The platform waits for your approval for a long time (hours). If you see "The read operation timed out" on a commit step, the agent gave up waiting before you approved. Approve sooner, or resume from the last safe checkpoint.

Redeploy

To deploy a new version (e.g. after pushing to GitHub), go to the project → Deployments and trigger a new deploy. The latest successful deployment is used for new runs.

← PreviousSDK reference