Getting started

From zero to your first agent run on RunForge.

What is RunForge?

RunForge is a platform to deploy and run AI agents. You connect a GitHub repo, the platform builds a container with your agent and the RunForge SDK, and you trigger runs from the dashboard. Agents can use safe steps (read-only, checkpointed) and commit steps (side effects that require human approval). You can also enable tools (Gmail, Google Calendar, Slack, etc.) and connect your accounts so the agent can act on your behalf.

Prerequisites

A RunForge account (sign up from the app)
GitHub account connected in RunForge (Settings or during project creation)
A repo with Python agent code using the agent-runtime SDK
Python 3.11+ in the repo (e.g. in agent.yaml or requirements.txt)

Repo setup

Your repo should contain at least:

agent.yaml (recommended) — name, entrypoint, python_version, browser, tools. The platform uses this to pre-fill project config.
requirements.txt — include agent-runtime (any version). The platform strips it at build time and injects the SDK.
An entrypoint module and function (e.g. agent:run) that creates an AgentRuntime and registers your agent with @app.agent("name").

If you don't have agent.yaml, you can still deploy: set entrypoint and name manually in the project config. See SDK reference for the exact agent pattern.

Minimal agent example

python

from agent_runtime import AgentRuntime

app = AgentRuntime()

@app.agent("my-agent")
def run(ctx, input):
    with ctx.safe_step("hello"):
        ctx.log("Hello from the agent")
        ctx.state["message"] = input.get("message", "world")
    return {"reply": "Hello, " + ctx.state["message"]}

Save as agent.py. Entrypoint: agent:run. See SDK reference for safe_step, commit_step, and tools.

First deploy

In the dashboard, go to Projects → New project.
Choose GitHub and connect GitHub if needed. Select your repo and branch.
The platform analyzes the repo (agent.yaml, requirements.txt). Confirm or edit Project name, Entrypoint, and Browser. Optionally enable Tools and select which ones.
Add any Environment variables your agent needs, then click Deploy.
Watch the build log (clone → analyze → build → start). When the deployment is ready, you can trigger runs.

First run

From the project Overview or Runs tab, click Trigger run. You can pass optional input JSON (e.g. {"message": "RunForge"}). The run is queued; a worker picks it up and executes your agent. View the run detail to see steps, logs, and artifacts. If your agent uses a commit step, the run will pause until you approve it in Approvals or the run detail page.

Next steps

SDK reference — full API for ctx, steps, and tools.
Deploy & run — detailed deploy flow, trigger run, and approvals.
Tools — enable Gmail, Calendar, etc., connect accounts, and use ctx.tools in your agent.

Next →SDK reference