Configuration

All Orbit configuration lives in a single orbit.yaml file at the root of your project. This file is the only Orbit artifact committed to version control — everything else (generated Terraform, state, env files) lives in .orbit/ and is gitignored.

Full Schema

apiVersion: astromesh/v1
kind: OrbitDeployment
metadata:
  name: my-astromesh              # Deployment name (used in resource naming)
  environment: production          # develop | staging | production

spec:
  provider:
    name: gcp                      # Cloud provider: gcp (aws, azure in roadmap)
    project: my-gcp-project-id     # GCP project ID
    region: us-central1            # GCP region

  compute:
    runtime:                       # Astromesh core runtime (agent execution)
      min_instances: 1             # Minimum running instances (0 = scale to zero)
      max_instances: 5             # Maximum instances under load
      cpu: "2"                     # vCPUs per instance
      memory: "2Gi"                # Memory per instance

  database:
    tier: db-f1-micro              # Cloud SQL machine tier
    version: POSTGRES_16           # PostgreSQL version
    storage_gb: 10                 # Storage allocation in GB
    high_availability: false       # Enable HA replica (doubles cost)

  cache:
    tier: basic                    # basic (no failover) | standard (HA)
    memory_gb: 1                   # Redis memory allocation

  secrets:
    provider_keys: true            # Create an empty <name>-fernet-key secret
    jwt_secret: true               # Generate <name>-jwt-secret on first deploy

  images:
    runtime: fulfarodev/astromesh:latest

  env:                             # Extra env vars for the runtime container
    ASTROMESH_LOG_LEVEL: INFO

Field Reference

metadata

Field	Type	Required	Description
name	string	Yes	Deployment name. Prefix for most cloud resources and the Terraform state. Use lowercase alphanumerics and hyphens (GCP naming rules; Orbit does not check).
environment	string	No	One of develop (default), staging, production. Recorded in the config; resource names do not depend on it.

spec.provider

Field	Type	Required	Description
name	string	Yes	Cloud provider identifier. Currently only gcp is supported.
project	string	Yes (GCP)	GCP project ID where resources will be created.
region	string	Yes	Cloud region for all resources. Example: us-central1, europe-west1.

spec.compute

The runtime compute service accepts the fields below. With no compute.runtime block at all, the runtime gets cpu: "2", memory: "2Gi", max_instances: 5; the table’s defaults apply to fields left out of a block you do declare.

Field	Type	Default	Description
min_instances	int	1	Minimum running instances. Set to 0 to enable scale-to-zero.
max_instances	int	3	Maximum instances Cloud Run will scale to under load.
cpu	string	"1"	vCPUs per instance, passed to Cloud Run as is (for example "1", "2", "4").
memory	string	"1Gi"	Memory per instance. Examples: "512Mi", "1Gi", "2Gi", "4Gi".

spec.database

Field	Type	Default	Description
tier	string	db-f1-micro	Cloud SQL machine tier. See GCP pricing.
version	string	POSTGRES_16	Cloud SQL database version, passed as is (for example POSTGRES_15, POSTGRES_16).
storage_gb	int	10	Disk storage in GB. Auto-grows when needed.
high_availability	bool	false	Enable regional HA with automatic failover. Roughly doubles the database cost.

spec.cache

Field	Type	Default	Description
tier	string	basic	basic for single instance, standard for HA with failover.
memory_gb	int	1	Redis memory in GB. Minimum 1, maximum 300.

spec.secrets

Field	Type	Default	Description
provider_keys	bool	true	Creates one empty Secret Manager secret, <name>-fernet-key, with no version. Add a value with gcloud secrets versions add.
jwt_secret	bool	true	Creates <name>-jwt-secret with a random 64-character value. It is generated once and kept in Terraform state, so later applies reuse it.

Caution

Neither secret is passed to the runtime container: the Cloud Run service does not mount or reference them. They are created for you to wire, through spec.env or by editing the ejected Terraform.

spec.images

Field	Type	Default	Description
runtime	string	fulfarodev/astromesh:latest	Container image for the Astromesh runtime.

spec.storage

Optional GCS resources for RAG documents and custom container images. Both blocks default to enabled: true.

spec:
  storage:
    rag_documents:
      enabled: true       # provision the GCS RAG documents bucket
      versioning: true    # keep object versions
    artifact_registry:
      enabled: true       # provision a Docker Artifact Registry repo
      repository: ""      # empty -> "<metadata.name>-images"

Field	Type	Default	Description
rag_documents.enabled	bool	true	Provision a GCS bucket for RAG source documents. The runtime receives its name as ASTROMESH_RAG_BUCKET.
rag_documents.versioning	bool	true	Keep object versions on the RAG documents bucket.
artifact_registry.enabled	bool	true	Provision a Docker Artifact Registry repository for custom images.
artifact_registry.repository	string	""	Repository name. Empty defaults to <metadata.name>-images.

Orbit does not provision a separate vector database for RAG — pgvector runs on the Cloud SQL instance Orbit already deploys. See GCP Provider for details.

spec.observability

Optional. The Cloud Monitoring dashboard is on by default; Cloud Trace is opt-in because its collector sidecar adds a container to every Cloud Run instance.

spec:
  observability:
    dashboard: true              # Cloud Monitoring dashboard (default: true)
    tracing:
      enabled: false             # OTel Collector sidecar -> Cloud Trace (default: false)
      collector_image: "otel/opentelemetry-collector-contrib:0.115.1"

Field	Type	Default	Description
dashboard	bool	true	Provision a Cloud Monitoring dashboard charting Cloud Run golden signals (requests, latency, error rate, instance count).
tracing.enabled	bool	false	Add an OpenTelemetry Collector sidecar to the runtime Cloud Run service and set ASTROMESH_OTLP_ENABLED=1 on the runtime container so it exports spans to Cloud Trace.
tracing.collector_image	string	otel/opentelemetry-collector-contrib:0.115.1	Container image for the OTel Collector sidecar.

spec.env

Field	Type	Default	Description
env	map of string → string	{}	Extra environment variables set on the runtime Cloud Run container, after the ones Orbit sets (see GCP Provider). Values are written into the rendered Terraform and the Cloud Run configuration in plain text, so do not put secrets here.

There is no logging field — Cloud Run ships container logs to Cloud Logging automatically. See GCP Provider for how orbit logs reads them.

Presets

The orbit init wizard offers two presets that fill in all values automatically; --preset starter|pro picks one without the prompt. Both presets also write the default storage and observability blocks (tracing off), omitted below.

Starter (~$15/mo)

Best for development, demos, and small teams.

apiVersion: astromesh/v1
kind: OrbitDeployment
metadata:
  name: my-astromesh
  environment: develop

spec:
  provider:
    name: gcp
    project: my-project-123
    region: us-central1

  compute:
    runtime:
      min_instances: 1
      max_instances: 3
      cpu: "2"
      memory: "2Gi"

  database:
    tier: db-f1-micro
    version: POSTGRES_16
    storage_gb: 10
    high_availability: false

  cache:
    tier: basic
    memory_gb: 1

  secrets:
    provider_keys: true
    jwt_secret: true

  images:
    runtime: fulfarodev/astromesh:latest

Pro (~$80/mo)

Best for production workloads with auto-scaling and high availability.

apiVersion: astromesh/v1
kind: OrbitDeployment
metadata:
  name: my-astromesh
  environment: production

spec:
  provider:
    name: gcp
    project: my-project-123
    region: us-central1

  compute:
    runtime:
      min_instances: 1
      max_instances: 5
      cpu: "4"
      memory: "4Gi"

  database:
    tier: db-g1-small
    version: POSTGRES_16
    storage_gb: 20
    high_availability: true

  cache:
    tier: standard
    memory_gb: 4

  secrets:
    provider_keys: true
    jwt_secret: true

  images:
    runtime: fulfarodev/astromesh:latest

Multiple Environments

metadata.environment does not change resource names. Most resources are prefixed with metadata.name (and the Terraform state uses it as its prefix), but the Cloud Run service (astromesh-runtime) and the service account (astromesh-orbit) have fixed names, so two deployments in one GCP project collide. Use a GCP project per environment.

Tip

You can maintain multiple orbit.yaml files for different environments (e.g., orbit.dev.yaml, orbit.prod.yaml) and pass them explicitly: astromeshctl orbit apply --config orbit.prod.yaml.

Working Directory

After orbit init and a first orbit plan/apply, your project will have:

your-project/
├── orbit.yaml           # Committed to git
└── .orbit/              # Gitignored
    ├── generated/       # .tf files (re-rendered on every plan/apply)
    │   └── .terraform/  # provider plugins and backend config
    └── orbit.env        # Terraform outputs, upper-cased (written after apply)

What’s Next

• GCP Provider — GCP-specific resource mapping and validation
• CLI Reference — All commands with flags and examples