forge-agent-runtime 0.1.0__py3-none-any.whl

forge_agent_runtime-0.1.0.dist-info/METADATA

@@ -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.

forge_agent_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+forge_runtime/__init__.py,sha256=uzGnG4FbdHGEWjkVquImoARA8AF4-usCgUzWIM6sYZA,656
+forge_runtime/api.py,sha256=OESanpWFJeIhctiBTp4XXFaUf9j3nmyxwkn94ferM7c,4675
+forge_runtime/cli.py,sha256=HtL8uRb6qCp12GPqGBIILNUmxR_a_oXGCPjraEeCeCM,14734
+forge_runtime/config.py,sha256=qZabx3nz8OPaRMe2kG-XqNuCZefa4vm3N8zNO-_i4Sw,2195
+forge_runtime/evaluation.py,sha256=3rvJE6EPoHTeI82qLVVFnJJrJpRIDyY2Xrls6MG2ttA,726
+forge_runtime/graph.py,sha256=6mIwOdAruTRGe23qslu6Ee9Ctt7LU1dadryjC81nGxc,2922
+forge_runtime/models.py,sha256=aXUsWOuBVgus_Ft1Oxoti-uoETlC79K1EWEA1d640XY,3529
+forge_runtime/orchestrator.py,sha256=_q3gGd-m6OkSmZk-GjHp2X7bH3pmEoFZN2OODCmEwfs,11890
+forge_runtime/registry.py,sha256=Sg8d7C19nOFDSwE8EPrNyUYuWyoyySEZhX4RH_Y9-Xk,10466
+forge_runtime/sandbox.py,sha256=JT9wM7YB4lZgSTxeT4Hkj09RmaQrqvrT0YDSqRsg7EQ,37644
+forge_runtime/storage.py,sha256=ctViXZ4fKxq5d2Yqhbc7XuzwBRepRpzt9ugPBPSJbRY,4228
+forge_runtime/workspace.py,sha256=gwmQjy_LissW6H3cUmnNQ3qBxsXPImqRnfE19HrE62Q,12543
+forge_runtime/providers/__init__.py,sha256=slHNb94H6kLyUibHZkTYkhrtVv0S4MXW29892XJ2jwU,35
+forge_runtime/providers/anthropic_provider.py,sha256=LANfUE0r8ITo1TC1xIs-4I52anyYtTGRkRbVkERy1bk,10492
+forge_runtime/providers/base.py,sha256=xTssjgbIkghth8vBl0HSfPsGnjFM_ryTQfdFOYg01lo,394
+forge_runtime/providers/factory.py,sha256=51JtrrnCsB-PDtZULar0HjKfxa33rq0Ll0vuJOK_2zM,1981
+forge_runtime/providers/mock.py,sha256=11hgq1tfGARv8iPNthXjE-qJEh0IROcrDnXqNs5bQ9Q,1864
+forge_runtime/providers/openai_provider.py,sha256=L4s7Dcv8kaBjbzSL1pcLtdbJYd-JwvxqDl2PNeAz_FM,11552
+forge_runtime/sandbox_assets/__init__.py,sha256=1DtyJxsY2Ax3GNWLVs2N-z5rFJm3RODrxZ8Y18W-UV8,66
+forge_runtime/sandbox_assets/Dockerfile,sha256=kWKehULCDMtHPt2xxK4ZPG5G3FDI8gDPfZcRuagKijk,1296
+forge_agent_runtime-0.1.0.dist-info/METADATA,sha256=dKUOUezw9NGoGQP9ENc2lsaIKoeMEp3L5ZK5fKtIXVY,17957
+forge_agent_runtime-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+forge_agent_runtime-0.1.0.dist-info/entry_points.txt,sha256=cwgQpbGT9zauIxxKwKDny5PEqBX-aOSp2giriKKe4_k,48
+forge_agent_runtime-0.1.0.dist-info/licenses/LICENSE,sha256=DjMXvPnWtt0Iq8cSxPaicC7SGTQVV1DEUpGECqqtmB8,812
+forge_agent_runtime-0.1.0.dist-info/RECORD,,

forge_agent_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

forge_agent_runtime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+forge = forge_runtime.cli:app

forge_agent_runtime-0.1.0.dist-info/licenses/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_runtime/__init__.py

@@ -0,0 +1,32 @@
+"""Forge Runtime public package interface."""
+from forge_runtime.models import (
+    AgentDefinition,
+    AgentRequest,
+    AgentResult,
+    ExecutionPlan,
+    RunRecord,
+    RunStatus,
+    SkillDefinition,
+    TaskSpec,
+    TaskStatus,
+)
+from forge_runtime.orchestrator import ForgeMaster
+from forge_runtime.registry import AgentForgeRegistry, RegistryError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentDefinition",
+    "AgentForgeRegistry",
+    "AgentRequest",
+    "AgentResult",
+    "ExecutionPlan",
+    "ForgeMaster",
+    "RegistryError",
+    "RunRecord",
+    "RunStatus",
+    "SkillDefinition",
+    "TaskSpec",
+    "TaskStatus",
+    "__version__",
+]

forge_runtime/api.py

@@ -0,0 +1,139 @@
+"""Optional local HTTP API for submitting and inspecting Forge runs."""
+from __future__ import annotations
+
+import secrets
+from ipaddress import ip_address
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from forge_runtime import __version__
+from forge_runtime.config import Settings
+from forge_runtime.orchestrator import ForgeMaster
+from forge_runtime.providers.factory import create_provider
+from forge_runtime.registry import AgentForgeRegistry, RegistryError
+from forge_runtime.storage import SQLiteStore
+
+settings = Settings()
+app = FastAPI(
+    title="Forge Runtime API",
+    version=__version__,
+    description="Local API for AgentForge-backed multi-agent orchestration.",
+)
+
+
+class CreateRunRequest(BaseModel):
+    goal: str = Field(min_length=1, max_length=20_000)
+    provider: str | None = None
+
+
+def authorize(
+    request: Request,
+    x_forge_api_key: Annotated[str | None, Header()] = None,
+) -> None:
+    """Require a token for non-loopback clients, regardless of the server bind address."""
+    if settings.api_token:
+        if not x_forge_api_key or not secrets.compare_digest(
+            x_forge_api_key, settings.api_token
+        ):
+            raise HTTPException(status_code=401, detail="Invalid or missing Forge API key.")
+        return
+
+    client_host = request.client.host if request.client is not None else ""
+    try:
+        is_loopback = ip_address(client_host).is_loopback
+    except ValueError:
+        is_loopback = False
+    if not is_loopback:
+        raise HTTPException(
+            status_code=401,
+            detail="Set FORGE_API_TOKEN and send X-Forge-API-Key for non-local access.",
+        )
+
+
+def get_store() -> SQLiteStore:
+    return SQLiteStore(settings.database_url)
+
+
+def get_registry() -> AgentForgeRegistry:
+    return AgentForgeRegistry(
+        local_path=settings.agentforge_local_path,
+        repository=settings.agentforge_repository,
+        ref=settings.agentforge_ref,
+        source=settings.agentforge_source,
+    )
+
+
+def get_runtime(provider_name: str | None = None) -> ForgeMaster:
+    registry = get_registry()
+    provider = create_provider(provider_name or settings.default_provider, settings)
+    return ForgeMaster(registry=registry, provider=provider, settings=settings)
+
+
+@app.get("/health", dependencies=[Depends(authorize)])
+def health() -> dict[str, str]:
+    return {"status": "ok", "service": "forge-runtime", "version": __version__}
+
+
+@app.get("/v1/agents", dependencies=[Depends(authorize)])
+def list_agents() -> list[dict[str, Any]]:
+    try:
+        registry = get_registry()
+        registry.load()
+    except RegistryError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    return [
+        {
+            "name": agent.name,
+            "description": agent.description,
+            "mode": agent.mode,
+            "recommended_skills": list(agent.recommended_skills),
+        }
+        for agent in registry.agents.values()
+    ]
+
+
+@app.get("/v1/skills", dependencies=[Depends(authorize)])
+def list_skills() -> list[dict[str, str]]:
+    try:
+        registry = get_registry()
+        registry.load()
+    except RegistryError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    return [
+        {"name": skill.name, "description": skill.description, "path": skill.path}
+        for skill in registry.skills.values()
+    ]
+
+
+@app.post("/v1/runs", status_code=201, dependencies=[Depends(authorize)])
+async def create_run(payload: CreateRunRequest) -> dict[str, Any]:
+    try:
+        runtime = get_runtime(payload.provider)
+        run = await runtime.execute(payload.goal)
+        return run.model_dump(mode="json")
+    except RegistryError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"Orchestration failed: {type(exc).__name__}: {exc}",
+        ) from exc
+
+
+@app.get("/v1/runs", dependencies=[Depends(authorize)])
+def list_runs(limit: int = 20) -> list[dict[str, Any]]:
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=422, detail="limit must be between 1 and 100.")
+    return get_store().list_runs(limit)
+
+
+@app.get("/v1/runs/{run_id}", dependencies=[Depends(authorize)])
+def get_run(run_id: str) -> dict[str, Any]:
+    run = get_store().get_run(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail="Run not found.")
+    return run