Trusted fast deploys#

Status: implemented for the access-controlled sites.smol.ai Alpha.

Forge can publish a small, buildless application without starting the repository build sandbox. This is a trusted control-plane optimization, not a weaker deployment mode: Forge still deploys one exact commit, validates every byte, produces immutable artifacts, applies the same runtime wrapper and policy, records a deployment, and activates only an eligible branch head.

The deployment page labels the selected path, explains the decision, shows the time to live and phase timings, and reports reused assets and runtimes. A repository never needs to choose the fast path.

Eligible repositories#

A deployment uses the fast path when all of these are true:

• the repository and site are already admitted to the Deploy trial;
• the Site configuration and forgeBuild.ts have no build command;
• forgeBuild.ts is present at the exact deployment commit;
• static assets are committed under app.assets.directory;
• an optional application entrypoint is a committed .js or .mjs file;
• the entrypoint is self-contained ESM with one default export and no imports;
• source plus assets fit the 1 MiB fast-source ceiling;
• the Git tree contains only regular files and directories; and
• the normal Forge manifest, application, asset, and quota checks pass.

TypeScript, package imports, generated assets, larger sources, and repository build commands automatically use the existing restricted sandbox. That is a supported fallback, not a deployment failure.

Example:

import { defineForge } from '@smolai/forge/config';

export default defineForge({
  version: 1,
  app: {
    entrypoint: 'src/server.js',
    assets: {
      directory: 'web',
      fallback: 'index.html',
    },
  },
  routes: [
    { pattern: '/api/*', to: 'app.http' },
    { pattern: '/*', to: 'app.assets' },
  ],
});

Execution flow#

flowchart LR
  Push["Forge Git push<br/>exact SHA"] --> Decide{"Fast-path eligible?"}
  Decide -->|yes| Read["Read verified Git objects<br/>from Forge R2"]
  Decide -->|no| Sandbox["Restricted exact-SHA sandbox"]
  Read --> Validate["Strict manifest, tree,<br/>source and asset validation"]
  Validate --> Parallel["Publish in parallel"]
  Parallel --> Assets["Reuse/upload assets<br/>by SHA-256"]
  Parallel --> Runtime["Reuse/publish site runtime<br/>by provider digest"]
  Sandbox --> Ingest["Trusted ingest"]
  Assets --> Activate["Record deployment<br/>and activate eligible head"]
  Runtime --> Activate
  Ingest --> Activate

Exact source without a clone#

The runner receives read-only access to Forge's Git-object bucket. It resolves only the deployment's stored repository ID and exact lowercase commit SHA. For each compressed Git object it:

1. inflates and parses the declared object type and length;
2. recomputes the canonical Git SHA-1 over the complete object;
3. rejects digest or size mismatches, invalid UTF-8 names, duplicate or unsafe paths, malformed trees, symlinks, gitlinks, and special file modes; and
4. walks only the manifest entrypoint and asset subtree required by the deployment.

The branch name is never used to select source after the deployment is created.

Content reuse#

Assets are stored at sites/content/sha256/<digest>. A version 2 trusted asset manifest maps each public path to exactly that validated key. Existing version 1 per-deployment manifests remain readable, so legacy static Sites are unchanged.

Dynamic code is wrapped and published per Site under a name derived from the Site identity and provider-artifact digest. The digest includes the application bundle, trusted-wrapper version, provider compatibility settings, and the private runtime binding. A later deployment with identical provider bytes reuses the ready script even if routes or deployment IDs differ.

This slice intentionally does not delete shared artifacts. Garbage collection needs reference accounting and is a separate operation.

Observability#

Each new deployment records:

• execution_path: trusted_fast or sandbox;
• a stable selection reason;
• source, validation, compile, asset, runtime-publication, activation, and total fast-path milliseconds;
• reused asset file and byte counts; and
• whether the dynamic runtime was reused.

Older deployments display “Path not recorded.” The API exposes the sanitized summary as one execution object and does not expose raw trusted manifests or storage keys.

Failure and rollout behavior#

• Eligibility failures fall back before a deployment is marked running.
• A failure after trusted publication starts fails the normal run and deployment; it does not silently retry in a different execution model.
• The global fast-path flag disables new fast deployments without affecting the sandbox or already-hosted Sites.
• Content-addressed uploads are idempotent, and runtime publication is reconciled through the Site runtime-artifact catalog.
• Production activation still verifies that the deployment SHA is the current configured branch head. Preview creation does not move production.

Fixture benchmark#

The controlled fixtures establish the sandbox baseline below. These verified results come from production deployment records after ordinary Forge Git pushes on July 23, 2026, not from a local microbenchmark. “Cold” includes the first content-addressed asset and runtime publication. “Reused” is a later exact-commit deployment with unchanged application content.

The reused deployments each reported two reused assets. Reservations and realtime also reported a reused runtime. The trial did not reach the aspirational 10× target consistently; the remaining latency is primarily control-plane activation and remote Git-object/database round trips, not repository build work.