Reference

Best Practices

Project setup

  • Always add requires: for the services you use. The platform only injects environment variables for declared dependencies.
  • Use grid dev instead of managing local databases. It provides isolated sandboxes with real data and automatic teardown.
  • Keep cloudgrid.yaml in your repo root. It is portable (no identity, no secrets) and safe to commit.
  • .cloudgrid/ is auto-added to .gitignore. Never commit it. Forks and clones start unlinked intentionally.

Deployment

  • Run grid dev and test locally before running grid plug.
  • Use grid plug --detach for long builds so you can continue working.
  • Use grid follow <trace_id> to re-attach to detached deploys.
  • Use grid rollback if a deploy introduces issues. It re-points at the previous image instantly.
  • Wire your GitHub repo (grid wire repo) for automatic deploys on push.

Security

  • Use grid secrets set for API keys, tokens, and connection strings. Never put secrets in cloudgrid.yaml or env vars.
  • Use vault: in cloudgrid.yaml for external database connection strings.
  • Set visibility to private or org unless you explicitly want public access.
  • Use callers: to control which entities can call yours. Default policy is manual with deny fallback.

Collaboration

  • Use spaces to organize entities by team, project, or purpose.
  • Set appropriate visibility for each entity. org is the safest default for internal tools.
  • Use grid fork when you want to build on someone else’s work while maintaining lineage.
  • Use grid clone when you want to take over an existing entity on a new machine.

Multi-service architecture

  • Keep services focused. One service per concern (API, frontend, worker, cron).
  • Use path: to route traffic to the right service. Set path: false for internal-only services.
  • Deploy order is automatic — when no service declares depends_on:, the platform sequences data stores → backend → frontend on first deploy and waits for each stage to be healthy. Declare depends_on: to control it yourself, or set deploy_order: off to disable.
  • Use calls: and callers: for cross-entity communication instead of hardcoding URLs.

AI Gateway

  • Declare requires: [ai] and use @cloudgrid-io/runtime (runtime.ai.*) instead of calling Claude or OpenAI directly. The gateway handles identity, metering, budgeting, and the per-Grid provider decision.
  • Use claude-haiku for high-volume, low-latency tasks. Use claude-sonnet as the default. Use claude-opus for tasks that need the highest capability.
  • Handle AI_BUDGET_EXCEEDED errors gracefully. The gateway enforces per-entity monthly token caps.

Agents

  • Start as an app, add the agent: block when you need scheduled autonomous behavior.
  • Set hard_stop: true on the budget to prevent runaway token spend.
  • Use the memory block to persist agent state across runs.