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          # dev | 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 empty Secret Manager entries for LLM API keys
    jwt_secret: true               # Auto-generate JWT secret on first deploy

  images:
    runtime: fulfarodev/astromesh:latest

Field Reference

metadata

Field	Type	Required	Description
name	string	Yes	Deployment name. Used as a prefix for all cloud resources. Must be lowercase alphanumeric with hyphens.
environment	string	Yes	One of dev, staging, production. Affects naming and default behaviors.

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:

Field	Type	Default	Description
min_instances	int	1	Minimum running instances. Set to 0 to enable scale-to-zero.
max_instances	int	5	Maximum instances Cloud Run will scale to under load.
cpu	string	"1"	vCPUs per instance. Valid values: "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	PostgreSQL version. Supported: 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 empty Secret Manager entries for LLM provider API keys. You populate them via GCP Console or gcloud.
jwt_secret	bool	true	Auto-generates a random JWT secret on first deploy. Subsequent deploys reuse the existing value.

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.

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. You can also pass --preset to skip the interactive wizard entirely.

Starter (~$15/mo)

Best for development, demos, and small teams.

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

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

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

  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: "2"
      memory: "2Gi"

  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

Environment Options

The metadata.environment field affects resource naming and default behaviors:

Environment	Naming Pattern	Notes
dev	{name}-dev-*	Suitable for development and testing
staging	{name}-staging-*	Pre-production validation
production	{name}-*	Production workloads (no environment suffix)

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 running orbit init, your project will have:

your-project/
├── orbit.yaml           # Committed to git
└── .orbit/              # Gitignored
    ├── generated/       # .tf files (regenerated on every plan/apply)
    ├── orbit.env        # Connection variables (written after apply)
    └── .terraform/      # Terraform cache and plugins

Roadmap Fields

spec.storage (v0.3.0) and spec.observability (v0.4.0) are implemented today — see spec.storage and spec.observability above. The following spec sections are still planned for future Orbit versions and are not yet implemented:

  # v0.5.0 — GPU & Inference
  # gpu:
  #   vllm:
  #     machine_type: g2-standard-4

  # v0.6.0 — Enterprise
  # custom_domain: agents.mycompany.com

What’s Next

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