# Forge Deploy overview

Status: architecture Phases 0–2 are live in the access-controlled
`sites.smol.ai` Alpha. Monorepo projects, authorization-aware private exact-SHA
builds, entitlement-sized connected ingest, the Forge-owned OpenNext preset,
and connected-domain control-plane records are implemented in the current
source branch but require a separate Forge release, provider provisioning, and
live verification. Multi-provider placement, general availability,
customer-managed Cloudflare accounts, and secrets remain roadmap work.

Forge Deploy is SmolForge's experimental hosting and runtime product. Static
Sites are one project kind within the same Deploy authority. Tasks remains the
autonomous coding product, and Runs remains CI and automation.

This is the product and platform overview: use it to understand what Deploy
owns, its current boundary, and which contract or operational guide to open
next. If you are configuring an application, start with the
[Alpha builder guide](forge-deploy-preview.md) instead.

For application builders, Deploy is the foundation of the
[Forge Sites application-services stack](../forge-sites-services.md): Forge
Build creates the exact-source release, Forge Identity supplies app-scoped end
users, Forge AI supplies bounded server inference, and Forge Agent is a clearly
labeled future end-user personalization service.

The target product loop is:

> Task or push -> exact commit -> checks -> immutable preview -> review ->
> production promotion -> rollback and audit.

Deploy is useful independently of Tasks. The first constrained dynamic release
therefore comes before the Devin/Tasks integration rather than waiting for the
entire agent loop.

## Choose your next document

- [Forge Sites application services](../forge-sites-services.md) explains the
  shared product model, current availability, and the boundary around the future
  Forge Agent.
- [`forgeBuild.ts` v1](manifest-v1.md) is the repository-authored contract for
  Build, Identity, AI, routes, and provider requirements.
- [Accounts, teams, service tiers, entitlements, and usage](accounts-entitlements.md)
- [Account operations](account-operations.md) explains the administrator
  growth dashboard, named abuse signals, warnings, and temporary request caps.
- [Forge Identity for hosted applications](forge-identity-v1.md) defines the
  app-scoped principal, disclosure scopes, session lifecycle, and runtime
  delivery boundaries.
- [Alpha builder guide](forge-deploy-preview.md) explains how to configure a
  repository, what applications receive, the live fixtures, performance, and
  current limits.
- [Pull request deploy previews](pull-request-previews.md) explains automatic
  exact-SHA builds, stable PR aliases, immutable URLs, and the initial
  same-repository safety policy.
- [Migrate an existing repository](migrating-an-existing-repository.md)
  explains the shared browser and `sf migrate` assistant, safe
  `forgeBuild.ts` authoring, and `main`/`master` selection.
- [Repository configuration](repository-config.md) defines the static
  `.forge/config.json` map for monorepo projects and reviewed Cloudflare
  binding proposals, including reserved-prefix routing and the separate
  inspect, import, and provider-apply gates.
- [Forge Assets v1](assets-v1.md) explains standard Git LFS compatibility,
  direct agent use of the LFS HTTP API without a local helper, the optional
  `.forge/assets.json` contract, smart hydration, zero-copy asset reuse, and
  the reviewed exact-SHA adoption API and migration-PR workflow.
- [AIE hosting release readiness](aie-hosting-release-readiness.md) separates
  merged source from the remaining OpenNext, migration, provider, preview, and
  production-cutover gates.
- [Deploy limits](limits.md) centralizes connected-asset, OpenNext, source, and
  configuration ceilings.
- [Operator runbook](operator-runbook.md) separates local implementation,
  provider provisioning, publication, promotion, domains, and live proof.
- [Failure diagnostics](failure-diagnostics.md) maps stable build and
  reconciliation failures to safe remediation.
- The live [`forgeBuild.ts` v1 specification](https://forge.smol.ai/spec/deploy/v1)
  and [JSON Schema](https://forge.smol.ai/spec/deploy/v1/schema.json) are the
  public build authoring contract. Repository-wide migration intent has a
  separate [JSON Schema](https://forge.smol.ai/spec/deploy/v1/repository-config.schema.json).
- [`@smolai/forge`](https://www.npmjs.com/package/@smolai/forge) provides
  `defineForge`, TypeScript types, the schema, and `smolforge deploy check`.

## Current behavior and roadmap

The [Forge Sites v1 contract](../forge-sites-v1.md) defines static applications
without dynamic runtime artifacts. All new deployments use the same
`forgeBuild.ts` control plane described here.

The documents in this directory describe the current trial and the proposed
next control plane:

- [Architecture](architecture.md) defines the merged system, contracts, data
  model, provider adapters, migration, and rollout.
- [`forgeBuild.ts` v1](manifest-v1.md) defines the implemented,
  repository-authored configuration contract and static evaluator.
- [Repository configuration](repository-config.md) defines the implemented
  static repository map and its non-deploying import workflow.
- [Application runtime](application-runtime-v1.md) defines the implemented
  preview HTTP, durable-state, and managed-realtime APIs plus future extensions.
- [Product and operations](product-operations.md) defines enablement,
  publishing, previews, resources, logs, quotas, abuse controls, and the
  operator workflow.
- [Security](security.md) defines trust boundaries, the temporary
  `sites.smol.ai` exception, egress policy, resource isolation, and production
  graduation gates.
- [Trial reliability](trial-reliability.md) records the observed end-to-end
  fixture incidents, immediate recoveries, and the reliability hardening
  backlog for the access-controlled Alpha.
- [Trusted fast deploys](trusted-fast-path.md) documents the implemented
  exact-Git-object fast path, sandbox fallback, content reuse, telemetry, and
  fixture benchmark.

Implementation status in an individual document takes precedence over older
design language. The `sites.smol.ai` Alpha is live, but it is not the final
general-availability security or domain boundary.

## Decisions already made

- SmolForge Git and an exact commit SHA are authoritative.
- Forge owns project configuration, environment policy, deployment history,
  provider placement, permissions, audit, usage, and billing.
- Execution providers never become the product's source of truth.
- Each repository may expose multiple independently enabled Deploy projects.
  Each project owns its root, releases, environments, provider target, active
  pointer, and rollback state.
- Private source is eligible only through current repository, account, project,
  exact-SHA, and frozen-entitlement authorization. No clone credential reaches
  the build sandbox.
- General availability allows any repository administrator to self-enable
  Deploy after automated eligibility checks and acceptance of the hosting
  Terms of Use.
- Production publication policy is configurable and defaults to automatic
  publication after a successful eligible build and a mandatory check
  baseline. `auto` is unavailable when the production branch does not meet its
  protection policy.
- Preview access is configurable.
- Build and runtime egress default to allowlists. A separately granted,
  per-project feature flag may allow broader public Internet access through a
  controlled outbound policy layer.
- The first dynamic release exposes one Forge application abstraction. Static
  assets, an HTTP handler, managed durable state, and managed realtime are
  available without choosing separate Workers, KV namespaces, or Durable
  Object deployments.
- Durable storage and realtime connections materialize lazily. The initial
  Cloudflare adapter uses SQLite-backed Durable Objects and mandatory WebSocket
  hibernation behind Forge-owned gateways.
- Realtime is deliberately bounded, state-mutation-emitted,
  browser-subscribe-only, non-authoritative, and able to fall back to budgeted
  conditional polling when sockets are
  technically unavailable. A policy or budget denial never causes extra
  polling. A site administrator may disable realtime without disabling
  durable state or HTTP. Repository-authored Durable Object classes and raw
  WebSocket handlers are deferred.
- Preview state is isolated from production by default.
- Cloudflare Workers for Platforms is the first dynamic adapter.
- Railway is a future adapter for persistent container services.
- Modal is a future adapter for asynchronous jobs, sandboxes, and GPU work.
- The repository contract is Forge-specific and provider-neutral. Provider
  escape hatches are explicitly non-portable.
- Applications name resources by required semantics rather than provider
  product: multiple databases, key/value stores, object stores, actors,
  services, or jobs are valid. The compiled plan records their concrete
  provider mappings.
- Deterministic preview seeds target those logical resource names. A provider
  change that needs data movement is an explicit migration, never an implicit
  consequence of deploying code.
- User code and build sandboxes never receive Forge or provider master
  credentials.
- Durable state is never destroyed merely because a new release stops
  accessing it.
- Connected Custom Domains and path routes use administrator-approved,
  project-scoped provider targets and an explicit apply action. Customer OAuth,
  arbitrary Cloudflare accounts, Cloudflare for SaaS, runtime secrets, and
  arbitrary provider bindings remain deferred.
- A connected `path_route` is a logical wildcard-free prefix. The safe default,
  `exact_and_descendants`, applies and receipts both the exact `host/prefix`
  route and the descendant `host/prefix/*` route. An explicitly reviewed
  `reserved_prefix` instead emits the terminal wildcard `host/prefix*`; this
  captures query-bearing roots and descendants while intentionally reserving
  lexical siblings such as `/prefix-old`. A main Custom Domain can remain the
  catch-all on the same hostname. Framework data URLs outside the prefix are
  still an application migration concern.

## Temporary hostname decision

Before production graduation, hosted content may use:

- Project: `{project}.sites.smol.ai`
- Immutable preview: `preview-{128-bit-random}.sites.smol.ai`
- Control plane: `forge.smol.ai`

This is intentionally a pre-production exception. It does not satisfy the
separate-registrable-domain production gate because hosted content and Forge
share `smol.ai`. The mandatory compensating controls and graduation criteria
are in [Security](security.md).

During this shared-domain period, projects and accounts require explicit Alpha
access. Repository administrators with Alpha access exercise the complete
self-service flow, but general availability and anonymous public hosting do not
open until the dedicated registrable domain exists.

A claimed hostname remains reserved to its original project and is not
reassigned. That durable claim does not guarantee continued serving or content
retention: Forge may suspend serving or revoke retained Alpha content.

Production graduation requires moving hosted content to a separate Forge-owned
registrable domain. URLs on `sites.smol.ai` must not be described as the final
production isolation boundary.

## Initial dynamic release

The smallest useful dynamic product is:

1. Read the project-root `forgeBuild.ts` from an exact authorized repository
   commit.
2. Create an environment-neutral release and build one application artifact,
   including its optional static assets, in the restricted runner.
3. Validate and ingest artifacts without exposing provider credentials.
4. Compile a trusted preview plan under preview policy.
5. For an application entrypoint, attach the lazy preview state facade and,
   when enabled, managed realtime.
6. Compile and publish the application through Workers for Platforms; the
   Worker and Durable Object topology remains internal.
7. Expose its immutable URL with configurable access.
8. For publication, apply the same release artifacts to production resources,
   verify a distinct production deployment, and activate it according to
   environment policy.
9. Serve through Forge routing with quotas, egress enforcement, logs, audit,
   suspension, and cleanup.

It does not include arbitrary Workers configuration, repository-authored
Durable Object classes, raw WebSocket handlers, customer Cloudflare accounts,
unrestricted networking, secrets, Node.js process compatibility, or multiple
providers in one release.

## Product vocabulary

| Product | Core objects | Purpose |
| --- | --- | --- |
| SmolForge | repository, issue, pull request | source and collaboration |
| Runs | workflow, run, job, step | CI and automation |
| Deploy | project, environment, release, deployment, application component | hosting and runtime |
| Tasks | task, attempt, workspace | autonomous coding |
| Sites | static Deploy project | compatibility surface for current static hosting |

## Next product gates

Before general availability, Forge still needs a separate registrable hosting
domain, general self-service beyond the current Alpha enrollment,
authenticated preview modes, a live-verified connected-domain rollout,
secrets, fuller cost/abuse operations, and a reviewed nonempty egress policy.
Seven-day preview retention and artifact cleanup are live in the Alpha.
Railway and Modal remain potential future adapters behind the same
provider-neutral Forge configuration.