soulsteads-agent-forge

mcp
Security Audit
Warn
Health Warn
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Warn
  • network request — Outbound network request in assets/forge-core.js
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Agent Forge is a self-hosted workflow runner for operators and teams that need to schedule work, inspect results, and recover after an interruption. Run and manage the same work through a local web dashboard, a CLI, an authenticated HTTP API, or a stdio MCP server.

README.md

Soulsteads Agent Forge

Run recurring workflows on your own machine, and see exactly what happened.

Agent Forge is a self-hosted workflow runner for operators and teams. Define a job, run it on demand or on a schedule, and inspect its steps, outputs, and failures. Use the local dashboard or CLI, or integrate through the authenticated HTTP API or stdio MCP server.

Quick start · Workflow guide · Operations · Backup and recovery

Early preview. Forge targets Linux, requires PostgreSQL, and listens on loopback only. The example below needs no model, provider key, harness, or plugin.

Agent Forge dashboard showing a successful release-readiness workflow and its three completed steps

The Runs view showing a completed workflow in a demo Forge home.

Quick start

You need Rust 1.97 or later, a C compiler, an empty, dedicated PostgreSQL database, and jq for the token command below. See the tested setup for what has been exercised.

1. Install and start Forge

From the root of this checkout, with the Cargo bin directory on your PATH:

cargo install --locked --path . -j 1
export FORGE_HOME="$HOME/.local/share/agent-forge-example"
agent-forge init

Set FORGE_DATABASE_URL privately to the connection URL for your dedicated database. Then start Forge in the foreground:

agent-forge serve --port 8110

Open http://127.0.0.1:8110 and sign in with the operator token at actors.operator.token in $FORGE_HOME/config.json. Keep that file private. To use the CLI, open a second terminal and load the same token without printing it:

export FORGE_HOME="$HOME/.local/share/agent-forge-example"
FORGE_TOKEN=$(jq -er '.actors.operator.token' "$FORGE_HOME/config.json") && export FORGE_TOKEN

2. Run a two-step workflow

Save this definition as report.json. The first step echoes a parameter; the second reads that step's output and returns a report.

{
  "type": "workflow",
  "input": {
    "params": {"task": "example checklist ready"},
    "steps": [
      {"id": "produce", "action": {"type": "echo", "input": {"text": {"$ref": "/params/task"}}}},
      {"id": "consume", "needs": ["produce"], "action": {"type": "echo", "input": {"text": "Observed: ${/steps/produce/output/text}"}}}
    ],
    "output": {"report": {"$ref": "/steps/consume/output/text"}}
  }
}

Validate, register, and run it:

agent-forge workflows validate --file report.json
agent-forge workflows create report --file report.json
agent-forge workflows run report --key first-report --wait

A successful run returns Observed: example checklist ready. Open Runs in the dashboard, or run agent-forge runs show RUN_ID with the ID returned by the CLI. If you lose the submission response, repeat the same command with the same request key and parameters instead of using a new key.

3. Put it on a schedule

This schedule runs report every day at 09:00 UTC:

agent-forge schedules create daily-report --work-id report --cron '0 9 * * *' --tz UTC
agent-forge schedules occurrences operator.daily-report

The history can be empty until the first due time. After that, follow the occurrence to its run and check the output; creating a schedule does not show that its work succeeded. Pause the example with agent-forge schedules pause operator.daily-report. Stop the foreground server with Ctrl-C; restart it with the same home and database to keep the definitions and history.

How Forge works

  • Execution and schedules: DBOS uses PostgreSQL for execution, checkpoints, schedules, and queues. A separate SQLite store in the Forge home records admissions and effect receipts; it does not replace PostgreSQL.
  • Permissions and extensions: The dashboard, CLI, API, and MCP use the same actor policy. Models, native agent harnesses, and executable plugins are optional and must be configured explicitly. Only install plugins you trust: they run with the service user's permissions.
  • Recovery: A checkpoint is not proof that an external action happened exactly once. If a run stops with an uncertain effect, verify what happened at the provider before reconciling it. Forge cannot undo an external action.

Documentation

I want to… Start here
Author workflows, pass parameters, or inspect results Workflow guide
Configure a credential for a specific workflow step Workflow credentials
Configure the service, actor permissions, CLI, API, or MCP Operations guide
Recover from an interruption, back up a home, or restore it Backup and recovery
Connect an agent harness or extend Forge Harnesses · Plugins · Agent operating skill
Check requirements, validate a build, or export source Requirements and verification · Source snapshots

Licensed under Apache-2.0. See third-party notices for bundled notices.

Reviews (0)

No results found