Content
<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
```bash
# Install (pick one)
brew install initializ/tap/forge
curl -sSL https://raw.githubusercontent.com/initializ/forge/main/install.sh | bash
# Create and run an agent
forge init my-agent && cd my-agent && forge run
# Connect to Slack
forge run --with slack
```
See [Quick Start](docs/getting-started/quick-start.md) for the full walkthrough, 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) | Get an agent running in 60 seconds |
| [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 |
| [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 |
| [Configuration](docs/reference/forge-yaml-schema.md) | `forge.yaml` schema and environment variables |
| [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.
