Skip to content
Astromesh Astromesh

Quick Start

You need:

  • Python 3.12+
  • OpenTofu or Terraform. Orbit uses $TOFU_PATH, then tofu, then terraform from your PATH.
  • A GCP project with billing enabled.
  • Credentials: gcloud auth login, or GOOGLE_APPLICATION_CREDENTIALS pointing at a service-account key. With a key, Orbit also sets up the private services access Cloud SQL needs; with gcloud you set it up once yourself (see GCP Provider).

  1. Install

    Section titled “Install”
    Terminal window
    pip install astromesh-cli "astromesh-orbit[gcp]"
    astromeshctl orbit --help

    The gcp extra brings the Google client libraries used for validation, the state bucket and VPC peering.

  2. Enable the APIs

    Section titled “Enable the APIs”
    Terminal window
    gcloud services enable run.googleapis.com sqladmin.googleapis.com redis.googleapis.com \
      secretmanager.googleapis.com vpcaccess.googleapis.com storage.googleapis.com \
      artifactregistry.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com \
      logging.googleapis.com --project my-project-123

    Orbit checks these ten but never enables them for you.

  3. Write orbit.yaml

    Section titled “Write orbit.yaml”
    Terminal window
    astromeshctl orbit init

    The wizard asks for the project, the region, a deployment name, the environment (develop, staging or production) and a preset: starter (about $15/month) or pro (about $80/month, with HA database and cache). It writes orbit.yaml and adds .orbit/ to .gitignore. --preset starter skips that question.

  4. Plan

    Section titled “Plan”
    Terminal window
    astromeshctl orbit plan

    Orbit validates credentials, project and APIs, creates the state bucket if needed, renders .orbit/generated/ and runs plan:

      Orbit Deployment Plan
    

      Validating... OK
      OK State bucket created: gs://my-project-123-astromesh-orbit-state
    

      Resources to create: …

    A failed check prints the command that fixes it and exits with code 1.

  5. Apply

    Section titled “Apply”
    Terminal window
    astromeshctl orbit apply

    It asks before creating billable resources (--auto-approve skips the question, for CI), then validates again and applies. The first apply takes several minutes; Cloud SQL and Memorystore are the slow ones. At the end it prints the runtime URL and writes .orbit/orbit.env.

  6. Verify

    Section titled “Verify”
    Terminal window
    astromeshctl orbit status
    curl "$(grep RUNTIME_URL .orbit/orbit.env | cut -d= -f2)/v1/health"

    status lists astromesh-runtime with its URL. orbit logs --since 10m shows what the container printed.

    To use the runtime from Cortex, add its URL as a remote runtime connection.

  7. Clean up

    Section titled “Clean up”
    Terminal window
    astromeshctl orbit destroy

    It asks first, then destroys everything Orbit created. The RAG bucket is created with force_destroy = false, so empty it before destroying or the destroy stops there. The state bucket is kept: delete it by hand once you are sure, with gsutil rm -r gs://my-project-123-astromesh-orbit-state.

Next steps

Section titled “Next steps”