Docs / Resource modes

Resource modes keep workspace services portable.

Repos declare the resource values their services need. The project or workspace chooses how those values are fulfilled: EnvForge-managed local, customer-provided, customer-cloud provisioned, or disabled. That keeps envforge.yml reviewable without turning it into a cloud console.

Review safe outputs Review workspace lifecycle

referencesworkspace injected

databaseresource.database.host

cacheresource.cache.url

storageresource.storage.bucket

mailresource.mail.smtp_url

queueresource.queue.url

Modes

One repo contract, four ways to fulfill it.

The application keeps asking for the same references. Workspace settings decide whether EnvForge runs something local, uses a resource the customer already has, provisions one in the customer cloud, or leaves it off.

EnvForge-managed local

EnvForge starts a workspace-scoped service for the branch and injects the same references the repo already asks for.

Customer-provided

The workspace points at a database, cache, bucket, mail sink, or queue the team already owns, without changing the repo contract.

Customer-cloud provisioned

EnvForge creates the approved resource in the customer account for that workspace, then writes the resolved values into service env files.

Disabled

The resource stays intentionally unbound for workspaces that do not need it, so services can skip optional features cleanly.

Mode selection

Choose the backing mode before changing app config.

Resource mode is a workspace decision that should be visible in review. Pick the provider posture first, then keep the repo contract stable so branch workspaces and production-like workspaces can share the same service inputs.

ModeUse whenReview before enablingRepo contract stays

Managed local

Fast branch work, tests, demos, and agent loops that need isolated data without customer-cloud setup.

Data reset policy, seed fixtures, storage persistence, and whether the resource can sleep with the workspace runtime.

The app still reads resource.database.host, resource.cache.url, or the matching product reference.

Customer-provided

Teams already own the database, cache, bucket, SMTP target, or queue and want workspaces to point at it.

Credential scope, network reachability, read/write limits, and whether branch traffic can touch shared state.

The repo keeps the same envforge.yml input names; only the workspace binding changes.

Customer-cloud provisioned

A branch needs a real cloud resource with customer ownership, isolation, tags, and lifecycle controls.

Provider account, region, tags, cleanup policy, cost owner, and the minimal IAM EnvForge may use.

Services receive resolved references at runtime instead of provider-specific Terraform or console values.

Disabled

Optional features, dry-run branches, or docs and marketing workspaces where the service should skip the integration.

Fallback behavior, health checks, and whether required services fail clearly when a disabled reference is requested.

Disabled is still an explicit workspace decision, not a deleted resource contract.

Resource references

Services ask for product resources, not provider wiring.

Database, cache, storage, mail, and queue resources are named by the role they play in the app. EnvForge resolves the backing provider at workspace start and injects the values where the service expects them.

Databaseresource.database.host

APIs ask for the database host, port, name, user, password, or full URL. The workspace decides whether that is a local Postgres or a customer-owned database.

Cacheresource.cache.url

Workers and APIs read one cache URL or namespace while EnvForge chooses a local Redis, a provided endpoint, or a cloud-provisioned cache.

Storageresource.storage.bucket

Services use a bucket, endpoint, region, and credentials reference without knowing whether files land in local S3-compatible storage or a customer bucket.

Mailresource.mail.smtp_url

Mail can resolve to a workspace mail sandbox, a provided SMTP target, a customer-cloud provider, or remain disabled for branches that should not send.

Queueresource.queue.url

Background jobs receive the queue URL or name through the same reference, whether the backing queue is local, provided, provisioned, or off.

Workspace injection

The repo names the reference. The workspace picks the provider.

This split lets repo owners review stable app requirements while operators choose the right mode per environment, branch, or project. Switching a database from managed local to customer-provided changes the workspace binding, not the application code.

Repo contract

envforge.yml declares resource references beside the service that consumes them, such as resource.database.host or resource.storage.bucket.

Workspace mode

The project or workspace selects the provider mode for each resource without asking repo owners to rewrite application config.

Runtime injection

When the runtime wakes, EnvForge resolves the selected provider and injects the values into declared service environment variables.

envforge.ymlrepo reference

version: 1
services:
  api:
    command: npm run api
    environment:
      DB_HOST: resource.database.host
      DB_NAME: resource.database.name
      REDIS_URL: resource.cache.url
      STORAGE_BUCKET: resource.storage.bucket
      SMTP_URL: resource.mail.smtp_url
      QUEUE_URL: resource.queue.url
resources:
  database:
    required: true
  cache:
    required: false
  storage:
    required: false
  mail:
    required: false
  queue:
    required: false