Forge Sites application services#

Forge Sites is more than a place to serve build output. A Site starts with an exact-source release and can opt into narrow Forge-managed services for end-user identity and server-side AI. A future Forge Agent service may add constrained end-user personalization, but it does not have a public runtime contract yet.

This page is the product map. Each linked specification remains authoritative for availability, security, configuration, and runtime behavior.

Service map#

The application owns product authorization, validation, abuse controls, and user experience. Forge owns the platform capability, release binding, mutable entitlement checks, usage admission, and revocation boundary.

One configuration surface#

forgeBuild.ts is the repository-authored capability declaration. It is evaluated from an exact commit and becomes part of the immutable release policy.

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

export default defineForge({
  version: 1,
  name: 'team-room',
  build: {
    command: 'pnpm run build',
    workingDirectory: '.',
  },
  app: {
    entrypoint: 'dist/server.js',
    assets: { directory: 'dist/client' },
    identity: {
      scopes: ['user:basic'],
    },
    ai: {
      profiles: {
        explainResult: {
          model: 'forge/text-fast@1',
          audience: 'server',
          funding: ['host'],
          maxInputTokens: 2_500,
          maxOutputTokens: 220,
          privacy: { contentLogging: 'off' },
        },
      },
    },
  },
  routes: [
    { pattern: '/assets/*', to: 'app.assets' },
    { pattern: '/*', to: 'app.http' },
  ],
});

Run smolforge deploy check before committing. A valid declaration proves only that the repository contract parses; it does not prove account entitlement, resource provisioning, release activation, or live runtime behavior.

Forge Build#

Forge Build is the foundation for the other services. It ties the source SHA, build plan, application artifact, assets, routes, capability policy, preview, production pointer, and rollback evidence together.

Start with:

• the forgeBuild.ts v1 contract;
• the Forge Deploy overview;
• the public Alpha guide; and
• the operator runbook when changing production.

Forge Identity#

Forge Identity gives each application a stable random ID for the visitor and, when requested, a small public-profile snapshot. Apps may also request the visitor's current Forge accounts or teams. The application never receives the Forge control-plane bearer token, session-signing secret, email address, or an unrestricted directory.

Use the smallest useful scope:

• user:basic for an app-specific user ID and public profile;
• accounts:read only when the product genuinely needs account membership and role context; and
• teams:read only when team membership affects the application.

Do not accept a browser-supplied principal as authority. The trusted runtime must bind the authenticated principal to every state-changing request. Native Forge applications and connected provider applications have different delivery paths, so check the Forge Identity v1 contract before choosing a deployment model.

Forge AI#

Forge AI exposes named, server-side profiles. A profile declares a logical model route, audience, funding source, input/output ceilings, response mode, privacy policy, and budgets. Application code still validates every result and keeps a deterministic or otherwise safe fallback.

Forge AI is not a browser API, a raw provider proxy, or the source of truth for permissions, prices, scoring, or other deterministic product behavior. See the Forge AI v1 guide for the native and connected runtime calls.

Forge Agent roadmap#

Forge already has a repository agent inside the Forge control-plane UI. That operator tool is not the proposed Forge Sites Agent.

The future Forge Sites Agent would let an application's end users submit a bounded personalization request, such as changing a theme, arranging a dashboard, or generating a user-owned configuration. The application would define:

• what resources the request may read and change;
• whether a human review is required before applying it;
• per-request and per-user time, compute, model, and storage budgets;
• the public progress and cancellation experience;
• an immutable audit receipt; and
• how to preview, reject, undo, or roll back the result.

The service must not expose repository administration, arbitrary source writes, Forge account authority, provider credentials, or production deployment controls to Site users. Until a reviewed manifest, runtime, authorization, budget, and rollback contract exists, Forge Agent remains roadmap material and must be labeled not available in product UI and marketing.

Where these services appear#

• The public landing page introduces the stack and current availability.
• A repository's Sites page shows Build as the foundation and links each attachable service to its guide.
• The docs home groups service contracts under Forge Sites services.
• smolforge deploy check validates repository-authored configuration.
• Deployment and runtime surfaces must report configured, admitted, injected, and live-verified states separately.