Forge Deploy product and operations#

Status: proposed behavior for review.

This document describes what repository administrators, contributors, agents, and operators experience. It intentionally separates requested configuration, successful build output, provider readiness, preview availability, and production publication.

Initial eligibility#

A repository administrator may enable the default Deploy project when all of the following are true:

• during the sites.smol.ai Alpha period, the owning account and project have Alpha access;
• the repository is public, active, and not deleted or suspended;
• the user and owning account are eligible for hosting;
• the current hosting Terms of Use are accepted;
• the requested hostname is valid, available, and not reserved;
• the manifest and requested capabilities pass validation;
• required abuse, quota, and billing checks are available;
• initial feature entitlements cover all requested capabilities.

Enablement records the actor, repository, project, terms version, configuration digest, policy-check results, feature entitlements, quotas, and timestamp.

The first UI exposes one default Deploy project per repository. The underlying model supports additional projects later without changing deployment identity. Self-service is limited to Alpha accounts until hosted content moves to a separate registrable domain.

The claimed hostname remains reserved to its original project through disablement, suspension, repository deletion, or Alpha revocation. Reservation does not guarantee continued serving or content retention: Forge may suspend the hostname and remove retained Alpha artifacts.

Repository Sites area#

The current repository-level Sites area evolves into Deploy while retaining a Sites label for the static compatibility path.

The project overview shows:

• project hostname and state;
• source root, manifest path, and production branch;
• publication policy and required checks;
• preview access mode and retention;
• effective build and runtime egress policy;
• application artifact and observed HTTP, asset, state, and realtime health;
• current production deployment;
• recent deployments grouped by source SHA;
• per-component build, publish, readiness, and error state;
• logs, usage, quotas, and audit history;
• controls to redeploy, promote, roll back, disable, or report a problem.

Provider IDs may appear in an advanced diagnostic view. They do not replace Forge status or become part of stable product URLs.

Configuration ownership#

Configuration is split deliberately:

Repository-owned intent#

forgeBuild.ts defines what the application needs:

• build command and one application artifact;
• application entrypoint, static assets, and routes;
• requested lower resource limits;
• requested egress requirements.

The forward resource contract uses stable, repository-chosen logical names and behavioral requirements rather than provider product names. It permits multiple resources of the same semantic kind. This is a design goal rather than current v1 syntax: the shipped v1 contract still exposes one application with built-in managed state and realtime.

Provider-specific configuration is allowed only under an explicit provider.<name> namespace. The Deploy UI and deployment receipt identify the affected capabilities as non-portable, show the selected provider resources in advanced evidence, and never imply that a provider extension can be migrated without semantic or data-movement work.

Trusted project and environment policy#

The Forge control plane defines what the application is allowed to do:

• repository eligibility and Terms acceptance;
• production branch and required checks;
• automatic or reviewed publication;
• preview visibility;
• egress ceiling and broad-public feature entitlement;
• provider availability and any future explicit-placement entitlement;
• durable-state and realtime quotas, retention, billing, and suspension;
• resource deletion authority.

The effective plan is the intersection of repository intent and trusted policy. A commit cannot grant itself broader egress, public preview access, production authority, higher quotas, provider credentials, or resource deletion rights.

Publication policy#

Each production environment has one policy:

Policy	Behavior
auto	Publish an eligible ready deployment automatically. This is the default only when the production branch satisfies the protection and check baseline.
owner_review	Require an authorized repository administrator to promote.
environment_review	Require an actor named by the protected environment policy.

Even auto requires:

• exact source SHA from the configured production branch;
• a protected production branch that agents and untrusted service identities cannot write directly;
• the mandatory manifest, build, trusted-ingest, policy, provider-readiness, preview-smoke, and security checks;
• source branch head, project configuration, and plan digest still current;
• all required checks passing;
• all required application components ready;
• repository, project, account, and billing eligibility still valid;
• no active suspension or takedown;
• during the shared-domain period, current project/account Alpha access;
• a compare-and-set update so a stale deployment cannot replace a newer production release.

An agent has no separate production authority. An agent may push an authorized task branch and open or update a pull request. Production follows the normal merge, check, and environment policy.

For an auto environment, anyone authorized to merge or directly update the protected production branch is deliberately a production deployer. If the branch or check baseline does not meet this contract, Forge changes the effective policy to owner_review; it does not silently retain auto.

Because application code can mutate retained production state and emit to connected realtime clients, the project UI must make this delegated production authority explicit when auto is selected. Rollback changes code and routes; it does not restore durable state or already delivered events.

On sites.smol.ai, auto may replace the active deployment for an enrolled project after exact-SHA, build, ingest, runtime, eligibility, and compare-and-set checks pass. Removing the project or account from the trial stops all of its routes.

Trigger behavior#

Initial triggers are:

• a successful push to the configured production branch;
• an authorized manual deployment of an exact commit;
• rebuilding an exact commit under a newly selected release-compiler or artifact-policy version;
• reapplying an existing ready release under a new environment policy, plan compiler, or provider-adapter version.

A source, manifest, release-compiler, build input, or artifact-policy identity change creates an environment-neutral release and builds its artifacts once. An environment-policy, plan-compiler, or provider-adapter change creates a new deployment from an existing ready release when its artifacts remain compatible; it does not rebuild merely to refresh provider state.

Forge applies each eligible ready release as an immutable preview deployment. Publication creates or reuses a distinct production deployment from the same release artifacts and binds the stable production state scope.

Automatic branch and pull-request previews should use the same durable ref-change event path as Git receive, API-created commits, merges, and future imports. They are added only after that unified event and outbox boundary exists. Agents can still create previews through ordinary authorized pushes and manual exact-SHA deployment during the initial dynamic release.

Release, deployment, and activation states#

The UI presents one pipeline while preserving four separate state machines.

Release#

State	Meaning
queued	Exact SHA accepted and waiting for compilation or capacity.
planning	Repository intent and the build graph are being normalized.
building	Immutable environment-neutral artifacts are being produced.
ready	All required release artifacts passed trusted ingest.
failed	Compilation, build, or ingest failed.
cancelled	An authorized cancellation reached a terminal state.

A ready release remains ready. Activation and rollback do not mutate release readiness.

Environment deployment#

State	Meaning
queued	A ready release is waiting to apply to an environment.
applying	Trusted adapters are provisioning the application's provider components.
verifying	Every applicable application component and shared gateway path is undergoing readiness checks.
ready	The release is usable in this environment and may be previewed or activated.
failed	A required application component or policy gate failed.
cancelled	The environment application was cancelled.
expired	A preview deployment and its unpinned endpoint reached retention.

All applicable application components are required in the initial version. Assets-only sites do not wait for HTTP, state, or realtime. Realtime-disabled sites verify the denial policy instead of provisioning a transport.

Activation#

An environment activation is requested, applying, active, failed, or compensated. awaiting_promotion, live, and superseded are UI projections from publication policy and activation history rather than deployment states.

Endpoint#

An endpoint is pending, active, revoked, retired, or expired. Endpoint expiry does not delete release artifacts or provider versions pinned by active or rollback-eligible production deployments.

The UI exposes release, application-component, resource-instance, operation, activation, and endpoint evidence. Provider components remain an advanced diagnostic. A failure shows which actions completed, whether cleanup is pending, and whether durable state changed.

Immutable previews#

Each ready preview deployment receives a preview such as:

https://preview-{128-bit-random}.sites.smol.ai

Preview access is snapshotted per deployment:

Mode	Behavior
public_unlisted	No authentication; high-entropy URL, no public enumeration, and noindex.
repository	Only authorized repository members.
share_token	Anyone with a scoped, revocable share link.

During the trial, public_unlisted is the default. The other modes remain reserved until their edge authentication and revocation paths are implemented. An unlisted URL is never described or treated as authenticated.

Repository access means any current actor with repository read permission. Membership removal, repository visibility changes, token revocation, or suspension increments an access epoch checked by the edge on every request.

Repository-authenticated previews use an edge-owned flow:

1. Forge creates a short-lived, single-use code scoped to the actor, deployment, hostname, return path, and current access epoch.
2. The browser navigates to reserved /.forge/access/bootstrap#code=...; the code remains in the fragment and is not sent in an HTTP request or referrer.
3. Edge-owned bootstrap code posts it to /.forge/access/exchange. The exchange is consumed before any repository code runs and all code fields are redacted from logs.
4. The edge issues a signed, short-lived, Secure, HttpOnly, host-only __Host-forge-access cookie with Path=/ and redirects to a clean return URL.
5. Every request validates deployment, hostname, expiry, access epoch, and current project eligibility. Before dispatch, the edge strips its access cookie and every edge-owned authentication header; repository code receives only application cookies and ordinary request headers.

Exact /.forge and the /.forge/* namespace are reserved and cannot be claimed by application routes. Forge bearer tokens and control-plane credentials are never sent to preview origins.

Share links use the same edge-owned bootstrap boundary:

1. The link contains the high-entropy share secret only in /.forge/access/bootstrap#share=....
2. The self-contained bootstrap page loads no third-party resources, clears the fragment from browser history, and posts the secret to /.forge/access/exchange before repository code runs.
3. The exchange compares the stored hash and issues a short-lived Secure, HttpOnly, host-only __Host-forge-access cookie with Path=/; the raw secret and credential are excluded from request and platform logs.
4. Every request checks the deployment's share-access epoch. Revoking or replacing the share link increments the epoch immediately.

Share secrets are scoped to one deployment and hostname, replaceable without rebuilding, and never placed in an ordinary query string or path.

Visibility changes, token revocation, repository visibility changes, deletion, disablement, and suspension must take effect without waiting for an immutable asset cache lifetime.

Production routing and rollback#

Production initially resolves:

https://{project}.sites.smol.ai

Production points to one ready application deployment. Promotion applies an existing ready release to the stable production environment; rollback selects or reapplies a previous release. Neither action rebuilds artifacts.

Rollback:

1. selects a previously ready production deployment or release;
2. verifies current repository and project eligibility;
3. verifies that its plan, compiled components, and retained state remain compatible;
4. performs required provider activation or compensation;
5. changes the active environment pointer with compare-and-set semantics;
6. records actor, reason, previous target, new target, and operation evidence.

The UI must distinguish an immediate pointer rollback from a provider re-activation that is still reconciling.

Rollback changes application code, assets, and routes only. Durable state does not roll back. Activation and rollback increment a realtime generation, stop new connections to the old generation, allow a short drain, and then close remaining sessions so clients reconnect and fetch a fresh snapshot. Stateful projects require an explicit acknowledgment, and Forge blocks any rollback that violates a declared application compatibility rule.

Managed application capabilities#

Repository authors deploy one application. They are not asked to choose between a Worker, Durable Object, key-value store, or companion realtime service. Forge exposes one portable runtime and compiles it into provider components.

Durable state#

Every application entrypoint may use env.forge.state. State storage is retained only after a successful mutation, so an application that never writes provisions no per-project data. An assets-only application creates no state usage.

The initial adapter uses Forge-owned SQLite-backed Durable Objects behind a trusted gateway; repository code receives neither a raw namespace nor a custom object class. Each project uses a fixed 16-shard production pool and each preview uses four shards; a trusted hash maps caller-selected scopes into that bounded pool.

Operations are strictly serializable within one caller-selected scope. There are no cross-scope transactions. A mutation may atomically commit state changes plus a versioned realtime event intent, which makes common reservation, counter, room, and coordination workflows safe without additional infrastructure. Live delivery remains best effort.

Production state belongs to the stable production environment and persists across deployments. Every immutable preview receives deployment-isolated state with a retention TTL. Preview data is never promoted into production, and rollback never rewinds production data. Destruction is a separate authorized operation with an impact summary and retention policy.

Managed realtime#

Every application entrypoint may use env.forge.realtime; the provider path materializes only when a state mutation emits an event or a client subscribes. The browser SDK subscribes through a reserved Forge endpoint. Repository code does not handle raw socket upgrades, connection lifecycle, or provider identifiers. Application code authorizes an ordinary HTTP request and directly returns an opaque subscription grant scoped to one state scope and topic. Only the trusted wrapper can turn that grant into ticket bytes, and the browser cannot choose a different scope after authorization.

Realtime is a convenience view over authoritative durable state:

• the server emits from an atomic state mutation and browsers subscribe; browser-to-server messages are not supported initially;
• events have a contiguous sequence within one (scope, topic) and carry a state version;
• replay, presence, exactly-once delivery, and durable connection state are not promised;
• a client connects and buffers before fetching an atomic versioned snapshot, then refetches after a gap or reconnect;
• the SDK uses hibernating WebSockets when available and may fall back to foreground-only conditional polling, within the same budget, when sockets are technically unavailable.

Connections, fan-out, bytes, topics, and lifetimes have conservative default ceilings. A repository may lower its limits. Raising them is an audited plan or feature-entitlement change, not a manifest request that silently increases spend. Realtime quota exhaustion stops realtime first and preserves normal HTTP, assets, and durable-state operations. A state mutation still commits when its event is suppressed; the sequence advances and affected clients are forced to resynchronize.

Activation, rollback, preview expiry, disablement, access revocation, and suspension invalidate affected sessions. Re-enable or unsuspend starts new authenticated sessions; it never restores old sockets or tickets. Suspension wakes the fixed shard pool, makes sessions inert through a fail-closed state/event gate, and then closes hibernating sockets.

Custom Durable Object classes, alarms, raw WebSocket handlers, client publishing, durable replay, and user-directed networking from managed state or realtime components remain deferred. Cloudflare Outbound Workers do not intercept Durable Object fetch() calls, so Forge does not run repository code inside those components.

Per-site configuration#

Each Deploy project receives one conservative application profile. A repository administrator can configure, per site:

• lower durable-state scope and storage ceilings;
• lower realtime connection, event-rate, fan-out, event-size, and daily-byte ceilings;
• realtime enabled or disabled;
• preview retention and preview realtime ceilings; and
• the runtime egress allowlist.

These settings describe outcomes and budgets, not provider products. The UI does not ask whether to create a Worker, Durable Object, namespace, or companion service. Repository limits may lower the trusted project settings. Only an audited entitlement or plan change can raise them.

Egress#

Build and runtime egress have separate policies.

The default runtime mode is a per-project allowlist. The requested destinations are versioned with the deployment plan, while the trusted control plane applies the final ceiling.

A project may receive a broad_public_egress feature flag. This means "arbitrary public Internet destinations through Forge's controlled outbound layer," not raw unrestricted networking. The outbound layer still blocks private and platform infrastructure, validates DNS and redirects, applies ports and size limits, meters usage, records bounded audit evidence, and supports immediate revocation.

All user-authored external requests originate in the application HTTP runtime and pass through the provider outbound policy. Forge-managed state and realtime components do not make user-directed external requests. Runtime code cannot modify its own egress entitlement.

Build behavior#

The existing restricted runner remains the build foundation:

• detached checkout at the exact source SHA;
• public source only initially;
• no Forge session, repository secret, provider credential, account ID, or deployment token;
• build egress limited by a separate dependency-oriented allowlist;
• typed output accepted only from declared unit paths;
• existing trusted validation rejects traversal, symlinks, special files, observed size changes, unsupported formats, and quota violations;
• trusted ingest stores immutable artifacts and manifests last.

Before dynamic artifacts are accepted, trusted ingest additionally requires file-identity and link-count checks, digest verification after the sandbox is quiescent, and tests for hard links and same-size mutation.

Every build network path applies the same private, loopback, link-local, metadata, internal-service, unsafe-port, DNS-at-connect, redirect, DNS-rebinding, credential, size, duration, and quota protections as runtime egress. The permitted public dependency registries form a separate build allowlist; the project's runtime egress setting never widens it.

Dynamic build output may include one Forge application bundle. Repository deployment commands and provider CLI credentials remain prohibited.

Logs and diagnostics#

Users can inspect:

• manifest and compiler diagnostics;
• build logs;
• trusted-ingest results;
• provider publication and readiness summaries;
• runtime logs subject to plan and retention limits;
• egress denials and quota events;
• durable-state contention and limit events;
• realtime connection, drain, fallback, and circuit-breaker summaries;
• promotion, rollback, suspension, and cleanup operations.

Large logs and artifacts live in object storage. Control-plane records hold bounded summaries, indexes, digests, and references.

Logs must be attributable to tenant, project, environment, deployment, application component, operation, and source SHA. Provider secrets, preview tokens, realtime tickets, bearer tokens, request credentials, and configured sensitive values are redacted before storage or display. Realtime message bodies are not logged by default.

Quotas and metering#

At minimum, meter and enforce:

• concurrent and queued builds;
• build minutes and sandbox size;
• compiler and provider operation attempts;
• CPU time, wall time, memory, and subrequests;
• runtime request count and duration;
• egress requests, bytes, and destinations by policy class;
• state scopes, operations, contention, duration, and stored bytes;
• realtime connections and connection time;
• realtime events, deliveries, fan-out, rejected work, and bytes;
• artifact count, stored bytes, and retention;
• preview count and lifetime;
• provider-specific billable units.

Every billable or externally mutating operation carries a tenant, project, deployment or resource target, idempotency key, and audit attribution.

Account and global circuit breakers must stop denial-of-wallet conditions even when an individual project remains within nominal quotas.

Disablement, suspension, and repository changes#

Repository administrators may disable a project immediately. Platform operators may suspend a repository, project, deployment, hostname, preview, runtime, account, or organization.

Serving checks current repository, project, deployment, access epoch, realtime generation, and suspension state before routing. Artifacts and provider endpoints are never exposed as an unguarded storage bypass.

A private, unlisted, deleted, or suspended source repository disables its public Deploy project immediately. Historical deployment and hostname records remain for audit and takeover prevention.

Suspension takes precedence over publication, rollback, feature flags, cached previews, and repository-admin actions.

State transitions are explicit:

Event	Routing and triggers	Retained state	Resume
Repository admin disables project	Stop routing and new triggers; increment desired, access, and realtime generations; drain active sessions; fence in-flight operations.	Active pointer, releases, deployments, hostname claims, and durable state remain.	Admin re-enables after fresh eligibility checks and explicitly confirms the prior active deployment.
Source becomes private or unlisted	Apply a source-visibility eligibility block immediately; stop routing and triggers.	Project state, pointer, history, hostname claims, and resources remain.	Returning public removes only the source block; an admin must revalidate before serving resumes.
Source is deleted	Stop routing and triggers; tombstone repository and hostnames.	Audit history and hostname tombstones remain; resource retention policy begins.	No automatic resume. Repository restoration and operator review are required.
Platform suspension	Stop routing, previews, triggers, promotion, rollback, and provider mutations except containment; revoke tickets and close active realtime sessions.	Evidence and quarantined resources remain under operator policy.	Only an authorized operator may lift suspension.
Billing or quota block	Stop new builds and mutations; serving behavior follows plan policy and global safety limits.	Existing releases and resources remain.	Reconcile eligibility before queued work or serving resumes.

Disablement and every blocking transition invalidate provider-operation leases. Public restoration, payment, or flag changes never resurrect a stale operation.

Audit and abuse operations#

The operator surface supports:

• append-only audit and usage records;
• public abuse reporting;
• phishing, malware, spam, open-proxy, cryptomining, and anomalous-egress triage;
• immediate suspension with actor and reason;
• artifact quarantine;
• takedown, appeal, restoration, and retention workflow;
• spend, traffic, error, and cleanup alerts;
• reconciliation of provider resources against Forge state.

The target suspension propagation SLO must be published and verified before production graduation.

Feature flags#

Initial flags should be explicit control-plane entitlements:

• deploy_application;
• broad_public_egress;
• realtime_extended_limits;
• future explicit_provider_placement;
• future railway_service;
• future modal_job;
• future runtime_secrets.

Durable state is part of deploy_application and has no separate provider feature flag. Managed realtime works within its conservative default limits; realtime_extended_limits authorizes only reviewed higher ceilings. Feature flags cap requested behavior. They are never passed to user code as provider credentials or management authority.

Acceptance scenarios#

Before constrained dynamic Deploy is enabled:

1. A repository administrator accepts current terms and enables an eligible public repository.
2. A push is built from the exact SHA and produces typed immutable artifacts.
3. An application cannot access raw provider bindings or a disallowed network target.
4. Two competing mutations in one state scope serialize, exactly one reservation wins, and the winning mutation atomically emits its version.
5. Preview state is isolated from production and expires according to policy.
6. Managed realtime enforces opaque scoped authorization, state-bound server emission, connect-before-snapshot sequencing, fan-out and spend limits, activation drains, and snapshot-based reconnect.
7. Polling fallback preserves the same authorization, generation, and quota semantics and never bypasses a denial.
8. Configurable preview access, revocation, and repository suspension work without cache delay.
9. Default automatic publication rejects stale branch heads, stale plans, failed checks, failed components, and suspended projects.
10. Owner-reviewed publication records its approver and compare-and-set result.
11. Rollback selects a prior ready release without rebuilding or rewinding state, and old realtime sessions reconnect against the new generation.
12. A failed provider operation is idempotently retried and its earlier attempt remains visible.
13. Explicit state destruction requires separate authority.
14. Broad-public egress still blocks metadata, private, platform, rebinding, redirect, unsafe-port, and quota-bypass cases.
15. All provider mutations, usage, promotion, rollback, suspension, and cleanup are attributable and reconcilable.