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

For application builders, Deploy is the foundation of the Forge Sites application-services stack: 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 explains the shared product model, current availability, and the boundary around the future Forge Agent.
• forgeBuild.ts v1 is the repository-authored contract for Build, Identity, AI, routes, and provider requirements.
• Accounts, teams, service tiers, entitlements, and usage
• Account operations explains the administrator growth dashboard, named abuse signals, warnings, and temporary request caps.
• Forge Identity for hosted applications defines the app-scoped principal, disclosure scopes, session lifecycle, and runtime delivery boundaries.
• Alpha builder guide explains how to configure a repository, what applications receive, the live fixtures, performance, and current limits.
• Pull request deploy previews explains automatic exact-SHA builds, stable PR aliases, immutable URLs, and the initial same-repository safety policy.
• Migrate an existing repository explains the shared browser and sf migrate assistant, safe forgeBuild.ts authoring, and main/master selection.
• Repository configuration 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 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 separates merged source from the remaining OpenNext, migration, provider, preview, and production-cutover gates.
• Deploy limits centralizes connected-asset, OpenNext, source, and configuration ceilings.
• Operator runbook separates local implementation, provider provisioning, publication, promotion, domains, and live proof.
• Failure diagnostics maps stable build and reconciliation failures to safe remediation.
• The live forgeBuild.ts v1 specification and JSON Schema are the public build authoring contract. Repository-wide migration intent has a separate JSON Schema.
• @smolai/forge provides defineForge, TypeScript types, the schema, and smolforge deploy check.

Current behavior and roadmap#

The Forge Sites v1 contract 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 defines the merged system, contracts, data model, provider adapters, migration, and rollout.
• forgeBuild.ts v1 defines the implemented, repository-authored configuration contract and static evaluator.
• Repository configuration defines the implemented static repository map and its non-deploying import workflow.
• Application runtime defines the implemented preview HTTP, durable-state, and managed-realtime APIs plus future extensions.
• Product and operations defines enablement, publishing, previews, resources, logs, quotas, abuse controls, and the operator workflow.
• Security defines trust boundaries, the temporary sites.smol.ai exception, egress policy, resource isolation, and production graduation gates.
• Trial reliability records the observed end-to-end fixture incidents, immediate recoveries, and the reliability hardening backlog for the access-controlled Alpha.
• Trusted fast deploys 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.

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.