forge

<p align="center"> <img src="assets/banner.png" alt="Forge — open-source AI agent framework" width="100%"> </p> # Forge — An Open, Secure, Portable AI Agent Runtime for the Enterprise <p align="center"> <a href="https://useforge.ai/docs/"><img src="https://img.shields.io/badge/Docs-useforge.ai-FFD700?style=for-the-badge" alt="Documentation"></a> <a href="https://discord.gg/PtFa4z97Ag"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a> <a href="https://github.com/initializ/forge/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-green?style=for-the-badge" alt="License: Apache 2.0"></a> <a href="https://initializ.ai"><img src="https://img.shields.io/badge/Built%20by-initializ-blueviolet?style=for-the-badge" alt="Built by initializ"></a> </p> Forge is the open-source runtime for Anthropic's Agent Skills standard — built for the agent that runs next to a service, in your environment, on infrastructure you already operate. Write a `SKILL.md`. Compile to a portable, hardened agent. Deploy it anywhere containers run: Kubernetes, on-prem, air-gapped, embedded in CI, or as an A2A endpoint. ## Why Forge? - **60-second setup** — `forge init` wizard configures provider, keys, channels, and skills - **Secure by default** — outbound-only connections, egress allowlists, encrypted secrets, no public listeners - **Portable** — same agent runs locally, in Docker, Kubernetes, or inside [Initializ Command](https://initializ.ai) - **Observable** — structured NDJSON audit logs with correlation IDs for every action - **Extensible** — add skills, tools, channels, and LLM providers without changing core code ## Quick Start Talk to a working agent, and watch it use a tool, in under 60 seconds: ```bash brew install initializ/tap/forge && forge try ``` `forge try` scaffolds a keyless demo agent, finds whatever model credential you already have, and drops you into a chat whose every tool call and egress check renders inline: ``` you › what's the weather in Tokyo, should I pack an umbrella? ▸ tool weather_current(location=Tokyo) ▸ egress wttr.in ✓ allowed ◂ 18C, light rain this evening agent › 18C in Tokyo with light rain tonight. Yes, take the umbrella. ``` Then build your own: `forge try --keep` graduates the demo to `./forge-quickstart`. See [Quick Start](docs/getting-started/quick-start.md) for the walkthrough, [Ship to Production](docs/getting-started/ship-to-production.md) for the full pipeline, or [Installation](docs/getting-started/installation.md) for all methods. ## How It Works ``` SKILL.md --> Parse --> Discover tools/requirements --> Compile AgentSpec | v Apply security policy | v Run LLM agent loop (tool calling + memory + cron) ``` You write a `SKILL.md`. Forge compiles it into a secure, runnable agent with egress controls, encrypted secrets, and audit logging. ## Key Features | Feature | Description | |---------|-------------| | Atomic Skills | `SKILL.md`-based agent definitions with YAML frontmatter | | Egress Security | Runtime + build-time domain allowlists with subprocess proxy | | Channel Connectors | Slack (Socket Mode), Telegram (polling) — outbound-only | | Cron Scheduling | Recurring tasks with channel delivery | | Memory | Session persistence + long-term vector search | | LLM Fallbacks | Multi-provider with automatic failover | | MCP Client | Connect to any HTTP MCP server (Linear, Notion, Atlassian, ...) — tools surface as `<server>__<tool>` with namespaced audit | | Web Dashboard | `forge ui` for browser-based agent management | | Build Signing | Ed25519 artifact signing & verification | | Air-Gap Ready | Runs with local models, no cloud required | ## Documentation ### Getting Started | Document | Description | |----------|-------------| | [Quick Start](docs/getting-started/quick-start.md) | Talk to an agent in 60 seconds with `forge try` | | [Ship to Production](docs/getting-started/ship-to-production.md) | The full init, build, package, deploy pipeline | | [Installation](docs/getting-started/installation.md) | Homebrew, binary, and Windows install | | [Architecture](docs/core-concepts/how-forge-works.md) | System design, module layout, and data flows | ### Core Concepts | Document | Description | |----------|-------------| | [Skills](docs/skills/writing-custom-skills.md) | Skill definitions, registry, and compilation | | [Binary Dependencies](docs/core-concepts/binary-dependencies.md) | How `forge build` resolves, installs, and places skill-declared binaries | | [Tools](docs/core-concepts/tools-and-builtins.md) | Built-in tools, adapters, and custom tools | | [Runtime](docs/core-concepts/runtime-engine.md) | LLM providers, fallback chains, running modes | | [Memory](docs/core-concepts/memory-system.md) | Session persistence and long-term memory | | [Context Compression](docs/core-concepts/context-compression.md) | Reversible compression of bulky tool outputs — fewer tokens, nothing lost | | [Channels](docs/core-concepts/channels.md) | Slack and Telegram adapter setup | | [Scheduling](docs/core-concepts/scheduling.md) | Cron configuration and schedule tools | | [Tracing](docs/core-concepts/observability-tracing.md) | OpenTelemetry distributed tracing — spans, propagation, audit cross-link | ### Security | Document | Description | |----------|-------------| | [Security Overview](docs/security/overview.md) | Complete security architecture | | [Authentication](docs/security/authentication.md) | Pluggable auth providers — OIDC, AWS Sigv4, GCP IAP, Azure AD | | [Egress Security](docs/security/egress-control.md) | Egress enforcement deep dive | | [Secrets](docs/security/secret-management.md) | Encrypted secret management | | [Build Signing](docs/security/build-signing.md) | Ed25519 signing and verification | | [Guardrails](docs/security/guardrails.md) | Content filtering and PII detection | | [Workflow Correlation](docs/security/workflow-correlation.md) | Orchestrator correlation IDs threaded through audit events | | [Platform Policy](docs/security/platform-policy.md) | Workspace-level deploy-time bounds on egress / tools / models | ### Operations | Document | Description | |----------|-------------| | [A2A Agent Card](docs/reference/a2a-agent-card.md) | Spec-conformant Agent Card at `/.well-known/agent-card.json` (A2A 0.3.0) | | [Commands](docs/reference/cli-reference.md) | Full CLI reference | | [The forge surface](docs/reference/forge-surface.md) | Bare `forge` — an interactive builder that shells into Claude Code (forge MCP tools) or forge's own agent, and generates `initializ-deploy.yaml` | | [Configuration](docs/reference/forge-yaml-schema.md) | `forge.yaml` schema and environment variables | | [Settings](docs/reference/settings.md) | Layered developer settings (user + managed/MDM) — enabled channels, model default + gateway, builtin tools | | [Dashboard](docs/reference/web-dashboard.md) | Web UI features and architecture | | [Deployment](docs/deployment/kubernetes.md) | Container packaging, Kubernetes, air-gap | | [Scheduler — Kubernetes](docs/deployment/scheduler-kubernetes.md) | Hybrid file/CronJob scheduler backend, RBAC, token plumbing | | [Hooks](docs/core-concepts/hooks.md) | Agent loop hook system | | [Library Modules](docs/reference/library-modules.md) | Import `forge-core`, `forge-skills`, `forge-plugins` as Go libraries — tag scheme, release pipeline, embedder API | | [Plugins](docs/reference/framework-plugins.md) | Framework plugin system | | [Command Integration](docs/reference/command-integration.md) | Initializ Command platform guide | ### For Claude / LLM-assisted contributors | File | Description | |------|-------------| | [Forge knowledge skill](.claude/skills/forge.md) | Single comprehensive markdown — drop it into a Claude conversation for full Forge context (architecture, security, APIs, CLI, audit pipeline, how to build agents + skills). | | [Forge skill-builder skill](.claude/skills/forge-skill-builder.md) | Same prompt the `forge ui` Skill Builder uses. Author a valid `SKILL.md` (frontmatter + body + optional scripts) in any Claude chat — no `forge ui` needed. | `/sync-docs` keeps both skills current — see `.claude/commands/sync-docs.md`. ## Philosophy Running agents that do real work requires **atomicity** (explicit skills, defined tools, declared dependencies), **security** (restricted egress, encrypted secrets, audit trails), and **portability** (runs locally, in containers, in Kubernetes, in cloud — same agent, anywhere). > Real agent systems require atomicity, security, and portability. Forge provides those building blocks. ## Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, how to add skills/tools/channels, and the PR process. Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating. ## License See [LICENSE](LICENSE) for details.