infrastructure/Agents.md

Agent System Reference

Quick reference for AI agents working in Will's infrastructure. Read this before doing any infrastructure work.

---

Machines

Machine	Role
Local Mac	Dev workstation (primary)

Legion is gone. All production services now run on GCP.

---

Production Environment — GCP

All production services run on Google Cloud Platform, project neuron-785695.

Service	URL	Platform
Marketing site	https://neurontechnologies.ai	Cloud Run (3 regions)
Accounts	https://accounts.neurontechnologies.ai	Cloud Run (3 regions)
REST API	https://api.neurontechnologies.ai	Cloud Run (3 regions)
Soma (AI inference gateway)	https://ai.neurontechnologies.ai	Cloud Run (us-central1)

Artifact Registry

Images are pushed to us-central1-docker.pkg.dev/neuron-785695/:

Service	Registry path
Marketing	neuron-marketing/marketing
Accounts	neuron-accounts/accounts
API	neuron-api/api
Soma	neuron-soma/soma

GCP CLI

gcloud auth login
gcloud config set project neuron-785695
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet

---

Secrets — GCP Secret Manager

GCP Secret Manager is the source of truth for all production secrets.

Access via gcloud CLI

gcloud secrets versions access latest --secret=<secret-name>

Secrets in use

Secret name	Purpose
jwt-secret	JWT signing key (accounts, api)
license-admin-token	License admin token (api)
accounts-database-url	Cloud SQL connection string (accounts)
soma-hf-token	HuggingFace API token (soma)
soma-operator-key	Soma operator/service key (soma)
stripe-secret-key	Stripe API key
stripe-webhook-secret	Stripe webhook signing secret
stripe-price-professional	Stripe Professional plan price ID
stripe-price-founding	Stripe Founding Member price ID

How secrets flow to Cloud Run

Secrets are injected as environment variables via Secret Manager references in Terraform Cloud Run service definitions. No ESO, no Vault.

GCP Secret Manager → Terraform secret_key_ref → Cloud Run env var → pod env

---

Infrastructure Management

The split: Terraform vs Cloud Run

Layer	Tool	What it owns
Infrastructure	Terraform	Cloud Run services, Artifact Registry, Secret Manager secrets, Load balancer, SSL certs, Cloudflare DNS, Cloud SQL, IAM
Secrets	Secret Manager	All production secrets — referenced in Terraform, never hardcoded

Never deploy Cloud Run changes with gcloud run deploy directly. All changes go through Terraform.

Running Terraform (GCP)

cd ~/Development/infrastructure/servers/gcp/
# direnv auto-loads credentials if configured, or:
export GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json
terraform plan
terraform apply

State is stored in Cloudflare R2 bucket legion-terraform-state (key: gcp/terraform.tfstate).

Repo layout

~/Development/
  infrastructure/                      ← this repo
    AGENTS.md                          ← you are here
    servers/
      gcp/
        *.tf                           ← Terraform (all GCP infra)
  neuron-technologies/
    soma/                              ← Soma AI inference gateway (Rust)
    neuron-rest/                       ← REST API (Go)
    accounts/                          ← Accounts service (Go)
    marketing/                         ← Marketing site (Next.js)

---

CI/CD

Gitea Actions (neuralplatform.ai was on Legion — now gone)

Gitea is gone with Legion. Use GitHub Actions for CI/CD.

• Workflows: .github/workflows/
• Push images to GCP Artifact Registry from CI using the neuron-ci-pusher service account
• CI SA key stored as GCP_SA_KEY repo secret (JSON key from neuron-ci-pusher@neuron-785695.iam.gserviceaccount.com)

Docker push pattern

gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
docker buildx build --platform linux/amd64 \
  -t us-central1-docker.pkg.dev/neuron-785695/<repo>/<service>:latest \
  --push .

---

Services & Domains

Domain	Backend	Notes
neurontechnologies.ai	GCP LB → Cloud Run	Marketing site, 3 regions
www.neurontechnologies.ai	GCP LB → Cloud Run	Marketing site alias
api.neurontechnologies.ai	GCP LB → Cloud Run	REST API, 3 regions
accounts.neurontechnologies.ai	GCP LB → Cloud Run	Accounts service, 3 regions
ai.neurontechnologies.ai	GCP LB → Cloud Run	Soma inference gateway, us-central1

All domains share one global anycast IP (marketing-ip-prod). DNS A records in Cloudflare point to that IP.

---

Load Balancer

• Global external HTTPS load balancer (marketing-urlmap-prod)
• Single IP (google_compute_global_address.prod)
• Host-based routing via URL map
• SSL certs: Google-managed, auto-renewed
• Cloud Armor: SQLi/XSS protection + rate limiting (1000 req/min per IP)
• CDN enabled for marketing site only

---

Terraform Cloudflare DNS

Cloudflare DNS A records for neurontechnologies.ai subdomains are managed in the GCP Terraform (servers/gcp/). The Cloudflare provider is configured via environment variable CLOUDFLARE_API_TOKEN.

Zone ID for neurontechnologies.ai: e844374f203dca4944d77d40ca0710ae

---

Key Paths

What	Where
This repo	~/Development/infrastructure/
GCP Terraform	~/Development/infrastructure/servers/gcp/
Soma (inference gateway)	~/Development/neuron-technologies/soma/
GCP credentials	~/.config/gcloud/
Secrets/tokens	~/Secrets/

---

What NOT To Do

• gcloud run deploy directly — use Terraform
• Hardcode any secret value — store in GCP Secret Manager
• Commit terraform.tfstate — state is in R2, never local
• Add kubernetes_* resources to Terraform — there is no k8s cluster anymore