Project Descriptor

A project descriptor is the compiled representation of your foundry.config.ts. The create-foundry-app CLI compiles your TypeScript config into this JSON shape and submits it to POST /projects/deploy. You can also construct and submit the descriptor directly via the API.

How the reconciler uses the descriptor

The diagram below shows what happens after POST /projects/deploy receives a descriptor: the reconciler plans which resources to create, provisions them in dependency order (databases and files first, then the app), injects connection environment variables, and brings the project to Running. Re-submitting the same descriptor is an idempotent no-op.

POST /projects/deploy, dependency-ordered reconciliation

RUNNING all resources provisioned · env wired

DescriptorPOST /deployfan-out →postgresRunningfilesRunningDATABASE_URL · S3_* · FOUNDRY_API_TOKEN →appRunning

DescriptorPendingProvisioning / wiringRunningDATABASE_URLS3_*auth issuer

Reconciliation phases

1. Submit. POST /projects/deploy accepts the descriptor and returns immediately. The reconciler picks it up asynchronously.
2. Plan. The reconciler diffs the descriptor against any existing project state and decides which resources to create, update, or leave unchanged.
3. Provision dependencies. Resources with no declared dependencies (typically postgres and files) are provisioned concurrently. The reconciler waits for each to reach Running before unblocking any resource that depends on it.
4. Provision the app. Once all dependency resources are Running, the app container is provisioned.
5. Wire connections. The reconciler injects connection environment variables (DATABASE_URL, S3_*, issuer_url, FOUNDRY_API_TOKEN) into the app and triggers a zero-downtime redeploy so the container starts with the full set of platform-managed variables.
6. Running. The project reaches Running once all resources are provisioned and wired.
7. Idempotent re-deploy. Submitting the same descriptor again produces a diff of zero changes. Every resource is already in the target state, so no work is done.

Top-level fields

Field	Type	Required	Description
name	string	yes	Stable project identity. Changing the name creates a new project rather than updating the existing one.
resources	array	yes	Every declared resource. Exactly one must have kind: app.
dependencies	object	no	Maps a resource logical_name to a list of logical_name values that must be Running before it is created.
organization_id	UUID	no	Scopes the project to an organization you belong to. Omit for a personal project.

Resources

Each entry in the resources array has three fields:

Field	Type	Required	Description
logical_name	string	yes	Unique name for this resource within the project. Used as the key in dependencies and as $name references inside other resources' specs.
kind	string	yes	One of postgres, files, auth, app.
spec	object	yes	Kind-specific configuration. Unknown keys are rejected.

Dependency ordering

The dependencies map expresses which resources must reach Running before a given resource is created. Independent resources provision concurrently.

{
  "dependencies": {
    "auth": ["db"],
    "web": ["db", "auth"]
  }
}

The engine also discovers implicit ordering edges from $logical_name references inside spec values: if the web spec contains "$db.service_id", the engine treats db as a dependency of web even if you did not list it explicitly.

When no dependencies key is present for a resource, the reconciler provisions it as soon as its own spec is valid. This means two independent postgres resources in the same descriptor provision in parallel.

postgres spec

Provisions a managed PostgreSQL service.

Field	Type	Default	Description
plan	string	tier-1	Compute plan name (e.g. tier-1, tier-2).
storage_gb	integer	25	Data disk size in GB.
storage_tier	string	platform default	Storage tier: standard or maxiops.
version	string	platform default	PostgreSQL major version (e.g. "17").
extensions	string array	none	Extensions to install (e.g. ["pgvector", "postgis"]).
default_database	string	defaultdb	Name of the default database created during provisioning.

files spec

Provisions an S3-compatible object storage bucket.

Field	Type	Default	Description
quota_gb	integer	none	Soft quota in GB (notification threshold).
quota_hard_gb	integer	none	Hard quota in GB (enforced ceiling).

auth spec

Attaches end-user authentication to the app resource. Auth does not create a standalone service; it enables an auth_configuration on the app it depends on. The auth resource must declare a dependency on the app resource (or the engine infers it from $ref notation).

Field	Type	Default	Description
providers	string array	["password"]	Enabled auth providers. Supported: password, google, github.
smtp	object	none	SMTP configuration for magic-link email delivery. If absent, email-based flows are disabled.
idp_providers	array	none	Social login provider configurations (client ID, secret).

When auth is enabled the reconciler records an issuer_url in the resource's outputs once the auth configuration is active.

app spec

Provisions a hosted application container.

Field	Type	Required	Description
image	string	yes	Container image reference (e.g. ghcr.io/myorg/myapp:latest).
port	integer	yes	The container port the application listens on.
env	object	no	Additional environment variables to inject alongside the platform-managed ones.
plan	string	no	Compute plan. Defaults to tier-1.
storage_gb	integer	no	Persistent storage for the app container.
custom_domains	string array	no	Custom domains to attach to the app.

Complete example

The following descriptor declares a to-do application backed by PostgreSQL with the pgvector extension, end-user auth with password and Google login, and an application container.

{
  "descriptor": {
    "name": "my-todo-app",
    "resources": [
      {
        "logical_name": "db",
        "kind": "postgres",
        "spec": {
          "plan": "tier-2",
          "storage_gb": 50,
          "storage_tier": "maxiops",
          "version": "17",
          "extensions": ["pgvector"]
        }
      },
      {
        "logical_name": "uploads",
        "kind": "files",
        "spec": {
          "quota_gb": 100
        }
      },
      {
        "logical_name": "auth",
        "kind": "auth",
        "spec": {
          "providers": ["password", "google"],
          "smtp": {
            "host": "smtp.example.com",
            "port": 587,
            "username": "noreply@example.com",
            "password": "smtp-secret"
          },
          "idp_providers": [
            {
              "provider": "google",
              "client_id": "your-google-client-id",
              "client_secret": "your-google-client-secret"
            }
          ]
        }
      },
      {
        "logical_name": "web",
        "kind": "app",
        "spec": {
          "image": "ghcr.io/myorg/todo:latest",
          "port": 3000,
          "plan": "tier-2",
          "env": {
            "NODE_ENV": "production",
            "LOG_LEVEL": "info"
          }
        }
      }
    ],
    "dependencies": {
      "auth": ["db"],
      "web": ["db", "uploads", "auth"]
    }
  }
}

When this project reaches Running, the web container will have the following environment variables injected by the platform, in addition to those declared in env:

Variable	Source
DATABASE_URL	PostgreSQL connection string for db
S3_ENDPOINT	Files endpoint for uploads
S3_BUCKET	Bucket name for uploads
S3_ACCESS_KEY	Access key ID for uploads
S3_SECRET	Secret access key for uploads
FOUNDRY_API_TOKEN	Scoped platform token (read-only: services, files)
FOUNDRY_API_URL	Base URL of the FoundryDB API

These variables are injected automatically. You do not declare them in env; doing so would override the platform-managed values with your literal string, which is almost never what you want.

Resource naming

The engine derives stable service names from the project name and the resource's logical_name. The same project-plus-logical-name always yields the same service name, which keeps re-deploys pointing at the same underlying service. Names are lowercased, sanitized to [a-z0-9-], and capped at 60 characters.

Next steps

• Deploying a project - how POST /projects/deploy handles the descriptor and what to poll.