Shared infrastructure

Runtimes get infrastructure wired in by declaring it in cloudgrid.yaml under needs:. The platform provisions each capability and injects its connection details as environment variables — you never manage connection strings or credentials by hand.

For the full schema and per-service overrides, see Infrastructure needs.

Database (MongoDB)

needs:
  database: true

The platform provisions Mongo and injects DATABASE_MONGODB_URL. Read it lazily in your code (never at module top level):

import { MongoClient } from 'mongodb';
const client = new MongoClient(process.env.DATABASE_MONGODB_URL);

The managed database is MongoDB. You can also bring your own Postgres, MySQL, or external MongoDB — see Infrastructure needs.

Cache and other Redis-backed needs

needs:
  cache: true    # Redis with LRU eviction  → CACHE_REDIS_URL
  kv: true       # Redis, no eviction        → KV_REDIS_URL
  queue: true    # Redis for queues (BullMQ) → QUEUE_REDIS_URL
  pubsub: true   # Redis pub/sub             → PUBSUB_REDIS_URL

Each need gets its own environment variable so your logical uses stay separate.

AI gateway

needs:
  ai: true

CloudGrid provides a built-in AI gateway that routes to Claude models with automatic metering, budgeting, and identity. The platform injects AI_GATEWAY_URL. Per-entity monthly token caps are enforced by the platform; when a cap is exceeded the gateway returns HTTP 429.

In production, identity is auto-detected from a platform-mounted token; in local dev (grid dev) it comes from your CLI credentials. No configuration is needed.

Object storage and disk

needs:
  object_storage: true   # a bucket → OBJECT_STORAGE_GCS_BUCKET / _REGION
  disk: true             # a persistent filesystem → DISK_PATH (default /data)

Use disk for a persistent filesystem that survives deploys and restarts (the successor to the older entity-level persist: field).

Vector search

needs:
  vector: pgvector   # → VECTOR_PGVECTOR_URL

The managed vector engine is pgvector (backed by Postgres).

Cron and agents

A scheduled job is a service of type: cron, not a need:

services:
  nightly:
    type: cron
    schedule: "0 3 * * *"
    timezone: UTC

An agent is an app with an agent: block (a purpose and a schedule). See the cloudgrid.yaml reference for the agent schema.

Local development

grid dev runs your services on your machine with the same grid resources tunneled in — the managed database and cache are reachable through injected environment variables, exactly as they are in production. See grid dev.