forge-agent-runtime 0.1.0__tar.gz

forge_agent_runtime-0.1.0/.env.example

@@ -0,0 +1,41 @@
+# Runtime
+FORGE_ENV=development
+FORGE_LOG_LEVEL=INFO
+FORGE_DATABASE_URL=sqlite:///./.forge/forge.db
+FORGE_WORKSPACE_ROOT=.
+FORGE_MAX_PARALLEL_TASKS=4
+FORGE_TASK_TIMEOUT_SECONDS=900
+
+# Sandboxed command execution for OpenAI/Anthropic agents (requires Docker)
+FORGE_SANDBOX_NETWORK=bridge
+FORGE_SANDBOX_ENABLED=true
+FORGE_SANDBOX_IMAGE=forge-runtime-sandbox:internet-v1
+FORGE_SANDBOX_DOCKER_BINARY=docker
+FORGE_SANDBOX_CPU_LIMIT=2
+FORGE_SANDBOX_MEMORY_MB=2048
+FORGE_SANDBOX_PIDS_LIMIT=128
+FORGE_SANDBOX_DEFAULT_TIMEOUT_SECONDS=180
+FORGE_SANDBOX_MAX_TIMEOUT_SECONDS=600
+FORGE_SANDBOX_OUTPUT_CHARS=24000
+FORGE_SANDBOX_MAX_SNAPSHOT_FILES=5000
+FORGE_SANDBOX_MAX_SNAPSHOT_MB=512
+FORGE_DEFAULT_PROVIDER=mock
+
+# AgentForge registry: auto uses the installed agentforge-toolkit wheel first.
+# Set source=local and path to a repository checkout to override packaged assets.
+FORGE_AGENTFORGE_SOURCE=auto
+FORGE_AGENTFORGE_REPOSITORY=https://github.com/mhingan/agent-forge
+FORGE_AGENTFORGE_REF=main
+FORGE_AGENTFORGE_LOCAL_PATH=
+
+# Hosted model providers (optional)
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1
+OPENAI_BASE_URL=
+ANTHROPIC_API_KEY=
+ANTHROPIC_MODEL=claude-sonnet-4-5
+
+# Local HTTP API (install forge-runtime[api] to use forge serve)
+FORGE_API_HOST=127.0.0.1
+FORGE_API_PORT=8787
+FORGE_API_TOKEN=

forge_agent_runtime-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install runtime, toolkit and test dependencies
+        run: python -m pip install -e ".[dev,api]"
+      - name: Lint and import normalization
+        run: |
+          ruff check . --fix
+          ruff check .
+      - name: Test
+        run: pytest --cov=forge_runtime --cov-report=term-missing
+
+  sandbox-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install Forge Runtime
+        run: python -m pip install -e ".[dev,api]"
+      - name: Build disposable agent toolchain image
+        run: forge sandbox build
+      - name: Verify Docker image and daemon
+        run: forge sandbox check
+      - name: Verify internet access inside sandbox
+        run: forge sandbox run -- curl --fail --silent --show-error --max-time 15 -I https://pypi.org
+      - name: Run complete suite inside sandbox
+        run: forge sandbox run -- bash -lc "PYTHONPATH=src python -m pytest -q"
+      - name: Lint inside sandbox
+        run: forge sandbox run -- ruff check src tests
+      - name: Verify read-write sandbox changes are applied
+        run: |
+          forge sandbox run --read-write -- python -c "from pathlib import Path; Path('.forge-sandbox-write-check').write_text('ok', encoding='utf-8')"
+          test "$(cat .forge-sandbox-write-check)" = "ok"
+          rm .forge-sandbox-write-check
+      - name: Verify read-only sandbox changes are discarded
+        run: |
+          forge sandbox run -- python -c "from pathlib import Path; Path('.forge-sandbox-readonly-check').write_text('must-not-escape', encoding='utf-8')"
+          test ! -e .forge-sandbox-readonly-check
+
+  package:
+    name: Build PyPI distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install packaging tools
+        run: python -m pip install --upgrade build twine
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Validate distribution metadata
+        run: python -m twine check dist/*
+      - name: Verify bundled sandbox Dockerfile
+        run: |
+          python - <<'PY'
+          import glob
+          import tarfile
+          import zipfile
+
+          wheels = glob.glob("dist/*.whl")
+          sdists = glob.glob("dist/*.tar.gz")
+          assert len(wheels) == 1, f"Expected one wheel, found {wheels}"
+          assert len(sdists) == 1, f"Expected one sdist, found {sdists}"
+          with zipfile.ZipFile(wheels[0]) as wheel:
+              assert "forge_runtime/sandbox_assets/Dockerfile" in wheel.namelist()
+          with tarfile.open(sdists[0], "r:gz") as sdist:
+              assert any(
+                  name.endswith("/src/forge_runtime/sandbox_assets/Dockerfile")
+                  for name in sdist.getnames()
+              )
+          print("Wheel and sdist both contain the sandbox Dockerfile.")
+          PY

forge_agent_runtime-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,115 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and validate distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out release source
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify release tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          actual = os.environ["RELEASE_TAG"]
+          if actual != expected:
+              raise SystemExit(
+                  f"Release tag {actual!r} does not match package version {expected!r}."
+              )
+          print(f"Preparing forge-agent-runtime {version}")
+          PY
+      - name: Install packaging tools
+        run: python -m pip install --upgrade build twine
+      - name: Check initial PyPI project name availability
+        if: github.event.release.tag_name == 'v0.1.0'
+        run: |
+          python - <<'PY'
+          import urllib.error
+          import urllib.request
+
+          url = "https://pypi.org/pypi/forge-agent-runtime/json"
+          try:
+              with urllib.request.urlopen(url, timeout=15) as response:
+                  if response.status == 200:
+                      raise SystemExit(
+                          "forge-agent-runtime is already registered on PyPI. "
+                          "Choose a different distribution name before publishing."
+                      )
+          except urllib.error.HTTPError as exc:
+              if exc.code != 404:
+                  raise
+          print("forge-agent-runtime is not currently registered on PyPI.")
+          PY
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Validate distribution metadata
+        run: python -m twine check dist/*
+      - name: Verify bundled sandbox Dockerfile
+        run: |
+          python - <<'PY'
+          import glob
+          import tarfile
+          import zipfile
+
+          wheels = glob.glob("dist/*.whl")
+          sdists = glob.glob("dist/*.tar.gz")
+          assert len(wheels) == 1, f"Expected one wheel, found {wheels}"
+          assert len(sdists) == 1, f"Expected one sdist, found {sdists}"
+
+          with zipfile.ZipFile(wheels[0]) as wheel:
+              assert "forge_runtime/sandbox_assets/Dockerfile" in wheel.namelist()
+
+          with tarfile.open(sdists[0], "r:gz") as sdist:
+              assert any(
+                  name.endswith("/src/forge_runtime/sandbox_assets/Dockerfile")
+                  for name in sdist.getnames()
+              )
+          print("Wheel and sdist both contain the sandbox Dockerfile.")
+          PY
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/forge-agent-runtime
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

forge_agent_runtime-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+dist/
+build/
+*.egg-info/
+.DS_Store

forge_agent_runtime-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+## Setup
+
+```bash
+python -m pip install -e ".[dev,api,openai]"
+```
+
+## Quality gates
+
+```bash
+pytest
+ruff check .
+```
+
+## Expectations
+
+- Keep runtime contracts independent from provider SDKs and API frameworks.
+- Do not invent AgentForge fields: integrate against the published 1.1.0 catalog and package API.
+- Validate every generated plan before dispatch.
+- Keep workspace file tools confined to the configured root; do not enable shell, network or deployment tools without a separately reviewed sandbox and permission model.
+- Add regression coverage for dependency ordering, concurrency, retries, failure propagation, registry compatibility and API authorization.
+- Update README, docs, roadmap and .env.example when behavior or configuration changes.
+- Never commit API keys, personal data, provider secrets or customer project context.

forge_agent_runtime-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Mihaita Hingan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

forge_agent_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.5
+Name: forge-agent-runtime
+Version: 0.1.0
+Summary: Docker-isolated multi-agent orchestration runtime for the AgentForge ecosystem
+Project-URL: Homepage, https://github.com/mhingan/forge-runtime
+Project-URL: Repository, https://github.com/mhingan/forge-runtime
+Project-URL: Issues, https://github.com/mhingan/forge-runtime/issues
+Author: Mihaita Hingan
+License: MIT License
+        
+        Copyright (c) 2026 Mihaita Hingan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+License-File: LICENSE
+Keywords: agentforge,agents,coding-agent,llm,multi-agent,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: agentforge-toolkit==1.1.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic-settings<3,>=2.2
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: rich<15,>=13.7
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1,>=0.28; extra == 'anthropic'
+Provides-Extra: api
+Requires-Dist: fastapi<1,>=0.115; extra == 'api'
+Requires-Dist: uvicorn[standard]<1,>=0.30; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=1.30; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Forge Runtime
+
+**A provider-neutral execution and orchestration engine for the AgentForge ecosystem.**
+
+Forge Runtime turns one user goal into a validated multi-agent execution graph. Forge Master selects specialist roles from AgentForge, asks an LLM provider to create a plan, validates the task dependencies, dispatches work concurrently, passes successful dependency results downstream, evaluates task outputs, and persists an execution history.
+
+## AgentForge integration
+
+Forge Runtime depends on the published distribution **agentforge-toolkit 1.1.0**. The toolkit exposes its bundled library directory through `agentforge.core.data_root()`; the runtime reads the catalogs and Markdown definitions from that packaged data.
+
+| Project | Responsibility |
+|---|---|
+| [AgentForge](https://github.com/mhingan/agent-forge) / [PyPI](https://pypi.org/project/agentforge-toolkit/1.1.0/) | Agent roles, skills, rules, workflows, catalogs, provider-specific coding-agent installation |
+| **Forge Runtime** | Forge Master, planning, DAG scheduling, dispatch, model-provider calls, state, evaluation, API and execution reports |
+
+The runtime does not call an undocumented AgentForge registry class or assume the toolkit is a hosted service. The adapter uses the package's real `data_root()` entry point. A local repository checkout and GitHub raw source are also supported.
+
+## Runtime capabilities
+
+- **Forge Master:** central coordinator for each execution run.
+- **AgentForge registry:** reads packaged roles, skills, rules and workflow playbooks.
+- **Planning:** OpenAI and Anthropic providers produce a structured execution plan; mock provider supports deterministic smoke tests.
+- **Task graph:** validates unique IDs, known roles/skills, dependencies, cycles and task limits before dispatch.
+- **Parallel scheduler:** independent tasks run concurrently under a configurable semaphore.
+- **Dependency context:** successful outputs are passed to tasks that depend on them.
+- **Workspace tools:** OpenAI and Anthropic agents can list, read, search and (for `read-write` roles) write files in a configured project workspace.
+- **Sandbox executor:** LLM agents can run tests, install dependencies and use the internet from disposable Docker containers with resource limits and controlled change-back.
+- **Retries and deadlines:** bounded attempts and per-task timeouts.
+- **Failure propagation:** tasks that depend on failed work are marked blocked.
+- **Evaluation:** baseline output validation behind a replaceable evaluator contract.
+- **Persistence:** SQLite records runs, task states, outputs and execution events.
+- **CLI and HTTP API:** inspect the registry, submit work and inspect run history.
+
+## Architecture
+
+```text
+                 User goal / CLI / HTTP API
+                            |
+                            v
+                    FORGE MASTER
+                            |
+               Load AgentForge toolkit data
+                            |
+                 LLM planner / Mock planner
+                            |
+                  Validate execution DAG
+                            |
+                     Task scheduler
+                 /         |          \
+                v          v           v
+           Architect    Backend      Product ...
+                |          |           |
+                +----------+-----------+
+                            |
+                 Dependency result hand-off
+                            |
+                   Evaluator / Retry
+                            |
+                      SQLite store
+                            |
+                 Run report + event history
+```
+
+AgentForge profiles and skills are untrusted model context, not executable permissions. OpenAI and Anthropic providers can modify ordinary files only inside `FORGE_WORKSPACE_ROOT`, and only when the selected role is `read-write`. Commands run inside Docker, never directly on the host. Git commit/push, browser, deployment and arbitrary MCP tools are not provided.
+
+## Requirements
+
+- Python 3.11+
+- AgentForge Toolkit 1.1.0 (installed automatically as a project dependency)
+- An API key only when using OpenAI or Anthropic
+
+## Install from source
+
+```bash
+git clone https://github.com/mhingan/forge-runtime.git
+cd forge-runtime
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[openai]"
+```
+
+The dependency installation also installs `agentforge-toolkit==1.1.0`. No separate AgentForge clone is required for the standard configuration.
+
+
+## Install from PyPI
+
+Once the first release is published:
+
+```bash
+python -m pip install "forge-agent-runtime[openai]"
+forge setup
+forge run "Inspect this project, implement the requested feature and run the tests"
+```
+
+For Anthropic, install `forge-agent-runtime[anthropic]`. The PyPI distribution is named `forge-agent-runtime`; the Python import package remains `forge_runtime`, and the command-line executable remains `forge`.
+
+## Quick start — two commands after installation
+
+From the project directory, run:
+
+```bash
+# Prompts for your OpenAI key, saves it safely in .env, and builds the Docker image
+forge setup
+
+# Give Forge a task; agents can edit files, install dependencies and access the internet
+forge run "Inspect this project, implement the missing features and run the tests"
+```
+
+Use `forge setup --provider anthropic` for Anthropic, or `forge setup --provider mock` for a no-key demo. Setup builds the sandbox image only once; later runs reuse it.
+
+The sandbox uses Docker's `bridge` network by default, which enables outbound internet access for commands such as `curl`, `wget`, `pip install`, `npm install` and Git operations. Set `FORGE_SANDBOX_NETWORK=none` in `.env` to run offline.
+
+## First run — mock provider
+
+```bash
+forge registry validate
+forge agent list
+forge skill list
+forge rule list
+forge workflow list
+
+forge run "Design a secure REST API for an e-commerce platform" --provider mock
+forge runs list
+```
+
+Mock mode verifies registry loading, planning, graph validation, scheduling, persistence and event creation without making model API calls. Its outputs are clearly marked as demonstrations; it does not produce real code changes.
+
+## Run with an LLM
+
+For OpenAI:
+
+```bash
+export OPENAI_API_KEY="..."
+export FORGE_DEFAULT_PROVIDER=openai
+forge run "Build a secure customer management API with tests"
+```
+
+Or choose a provider per run:
+
+```bash
+forge run "Review the backend architecture" --provider openai
+forge run "Plan a Flutter application" --provider anthropic
+```
+
+Optional provider installs:
+
+```bash
+python -m pip install -e ".[openai]"
+python -m pip install -e ".[anthropic]"
+```
+
+The LLM providers have bounded workspace and Docker command tools, but no direct host shell or deployment access. Their command execution runs in disposable containers.
+
+## Workspace access for coding tasks
+
+OpenAI and Anthropic providers expose bounded workspace tools during specialist execution:
+
+| Tool | Capability | AgentForge permission |
+|---|---|---|
+| `workspace_list_files` | List project files | read-only and read-write |
+| `workspace_read_file` | Read UTF-8 source files | read-only and read-write |
+| `workspace_search_files` | Search source text | read-only and read-write |
+| `workspace_write_file` | Create or replace UTF-8 files | read-write only |
+| `workspace_run_command` | Run allowlisted developer commands in isolated Docker | read-only and read-write |
+
+The default workspace is the directory from which `forge` is launched. Set `FORGE_WORKSPACE_ROOT` to select a specific project. The runtime confines paths to that root and rejects traversal paths, drive-qualified paths, symlinks that escape the root, secret environment files and private-key files. It excludes common dependency/build directories and caps file sizes, search results, tool rounds and total tool calls.
+
+Example:
+
+```bash
+export FORGE_WORKSPACE_ROOT="/path/to/my-project"
+export OPENAI_API_KEY="..."
+forge run "Inspect the project, implement a responsive settings page, and add tests" --provider openai
+```
+
+The model can read and write files through workspace tools. Command execution is a separate Docker capability described below. Mock mode never modifies files. Review the resulting diff before using changes in production.
+
+## Sandboxed command execution
+
+Install and start Docker Desktop or Docker Engine. The first setup builds a local toolchain image and verifies that the sandbox can reach the internet.
+
+```bash
+# Check the Docker daemon and configured image
+forge sandbox check
+
+# Build forge-runtime-sandbox:internet-v1 once
+forge sandbox build
+
+# Smoke-test the image
+forge sandbox run -- python --version
+forge sandbox run -- pytest --version
+
+# Run the project's tests in a disposable container
+forge sandbox run -- python -m pytest
+```
+
+The LLM providers expose `workspace_run_command`. The tool accepts an argv array, not a raw shell string. Typical commands include `python -m pytest`, `ruff check .`, `mypy`, `npm test`, `node --test` and `make test`. Shells (`bash`/`sh`) are available inside the container for project scripts, but never on the host.
+
+The sandbox uses Docker bridge networking for internet access, a read-only container root filesystem, dropped Linux capabilities, `no-new-privileges`, a non-root UID, PID/CPU/memory limits, an execution timeout and capped output. It receives a sanitized temporary copy of the project, excluding `.git`, environment secrets, credentials, private keys, dependency folders and common build caches. With internet enabled, `node_modules` is a temporary writable volume for package installation; in offline mode, an existing local `node_modules` may be mounted read-only. No host API keys or environment variables are forwarded.
+
+For AgentForge `read-write` roles, newly created or modified regular files are copied back after the command. Deletions and symlinks are not copied back. For `read-only` roles, all container changes are discarded. A failed test command still returns stdout, stderr and its exit code so the agent can diagnose, fix and rerun.
+
+The default image includes Python, pytest, Ruff, mypy, Node.js/npm, Git and common build tools. Projects requiring additional Python, Node or system libraries should customize `src/forge_runtime/sandbox_assets/Dockerfile`, rebuild the image and set `FORGE_SANDBOX_IMAGE` if using a different tag. Runtime containers never pull missing images automatically; run `forge sandbox build` explicitly.
+
+Set `FORGE_SANDBOX_ENABLED=false` to remove command execution from model tool schemas. This is a Docker container boundary, not a VM: run Docker Engine on a trusted host, keep it patched and review agent changes before merging.
+
+## Registry source selection
+
+The default setting `FORGE_AGENTFORGE_SOURCE=auto` loads the packaged AgentForge data via `agentforge.core.data_root()`.
+
+| Setting | Behavior |
+|---|---|
+| `auto` | Use installed toolkit; fall back to GitHub when it is unavailable |
+| `installed` | Require installed `agentforge-toolkit` package data |
+| `local` | Use `FORGE_AGENTFORGE_LOCAL_PATH` |
+| `github` | Fetch catalogs and referenced Markdown from the configured GitHub ref |
+
+For a local AgentForge checkout:
+
+```bash
+export FORGE_AGENTFORGE_SOURCE=local
+export FORGE_AGENTFORGE_LOCAL_PATH="../agent-forge"
+forge registry validate
+```
+
+## Local HTTP API
+
+Install the API extra and start the service:
+
+```bash
+python -m pip install -e ".[api]"
+forge serve
+```
+
+Default address: `http://127.0.0.1:8787`. Interactive API documentation is available at `/docs`.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/health` | Service health |
+| GET | `/v1/agents` | AgentForge agent catalog |
+| GET | `/v1/skills` | AgentForge skill catalog |
+| POST | `/v1/runs` | Submit a goal and execute the run |
+| GET | `/v1/runs` | List recent runs |
+| GET | `/v1/runs/{run_id}` | Read run, task and event records |
+
+Example:
+
+```bash
+curl http://127.0.0.1:8787/v1/agents
+
+curl -X POST http://127.0.0.1:8787/v1/runs \
+  -H "Content-Type: application/json" \
+  -d '{"goal":"Plan a secure inventory API","provider":"mock"}'
+```
+
+The API executes a submitted run synchronously and returns the final run record. This is a local control API, not yet a durable background job service. Keep it bound to localhost for personal development. For a network bind, set a strong `FORGE_API_TOKEN`; send it as `X-Forge-API-Key`.
+
+## Configuration
+
+See `.env.example` and [the PyPI publishing guide](docs/publishing.md).
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `FORGE_DEFAULT_PROVIDER` | Default model provider | `mock` |
+| `FORGE_MAX_PARALLEL_TASKS` | Max concurrent tasks | `4` |
+| `FORGE_TASK_TIMEOUT_SECONDS` | Per-task timeout ceiling | `900` |
+| `FORGE_DATABASE_URL` | SQLite database URL | `sqlite:///./.forge/forge.db` |
+| `FORGE_WORKSPACE_ROOT` | Project directory visible to the runtime | `.` |
+| `FORGE_SANDBOX_ENABLED` | Expose Docker command tool to LLM agents | `true` |
+| `FORGE_SANDBOX_IMAGE` | Prebuilt local Docker image name | `forge-runtime-sandbox:internet-v1` |
+| `FORGE_SANDBOX_NETWORK` | Sandbox network (`bridge` or `none`) | `bridge` |
+| `FORGE_SANDBOX_CPU_LIMIT` / `MEMORY_MB` | Per-container CPU and memory limits | `2` / `2048` |
+| `FORGE_SANDBOX_DEFAULT_TIMEOUT_SECONDS` | Default command timeout | `180` |
+| `FORGE_AGENTFORGE_SOURCE` | Registry source selection | `auto` |
+| `OPENAI_API_KEY` | OpenAI key | unset |
+| `ANTHROPIC_API_KEY` | Anthropic key | unset |
+| `FORGE_API_TOKEN` | HTTP API key for network binds | unset |
+
+## Security and limitations
+
+- All user goals, registry files and model outputs are treated as untrusted content.
+- Plans are validated against installed AgentForge role and skill names before any task runs.
+- The scheduler enforces bounded concurrency, retries and timeouts.
+- OpenAI and Anthropic agents can change ordinary files only inside `FORGE_WORKSPACE_ROOT` and only with a `read-write` role; secrets are excluded from workspace tools and sandbox snapshots.
+- Shell/test/build commands run only inside ephemeral Docker containers. Bridge mode provides outbound internet and may reach private/LAN destinations accessible from the Docker host. Use `none` for offline tasks. This is container isolation, not a VM or protection from host-kernel/Docker-daemon vulnerabilities.
+- The sandbox does not provide Git commit/push, deployment, browser access or arbitrary MCP tools. Deletions are not copied back.
+- Tasks flagged as requiring human approval are rejected because the approval subsystem is not enabled yet.
+- SQLite is intended for local and single-process use; it is not a distributed job queue.
+- The baseline evaluator checks output presence and size; it is not a semantic correctness guarantee.
+- The HTTP API should not be exposed publicly without a hardened deployment, authentication, TLS and tenant isolation.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev,api]"
+pytest
+ruff check . --fix && ruff check .
+```
+
+See [architecture](docs/architecture.md), [provider contracts](docs/providers.md), [sandbox details](docs/sandbox.md), [security](docs/security.md), [roadmap](ROADMAP.md) and [contributing](CONTRIBUTING.md).
+
+## License
+
+MIT.