Themelio compatibility reference. This page describes the retained Themelio implementation or its historical design. Check the parallel-operation guide before applying it to the current platform.

#Networking

This page describes how traffic reaches Themelio's services and how deployed workloads (model inference endpoints, spaces) get routable URLs.

#Ingress Architecture

Themelio uses Istio as its service mesh and ingress layer. Traffic enters through two separate Istio IngressGateways, each handling a distinct class of requests:

#Web Gateway

Handles all platform traffic — the web UI, API routes, and git operations:

• Web requests route to the Themelio Web service (Next.js on port 3000)
• Git smart HTTP requests (*.git/git-receive-pack, *.git/git-upload-pack, *.git/info/refs) route to GitLab

The split happens at the VirtualService level based on URI pattern matching.

#Service Gateway

A dedicated gateway for user-deployed workloads — spaces, inference endpoints, and custom action deployments. This gateway runs as a separate Istio IngressGateway (istio-ingressgateway-service) in the istio-system namespace.

Keeping workload traffic on its own gateway means platform traffic and user workload traffic scale independently.

#How Deployed Workloads Get URLs

When k8s-root-actor deploys a space, inference endpoint, or custom action, it creates three Kubernetes resources:

1. A Pod or Deployment running the workload
2. A ClusterIP Service exposing the pod internally
3. A VirtualService + Gateway routing external traffic to the service

#URL Generation

Each deployment gets a deterministic URL based on its identity:

• Spaces: https://<host>/-/iframe/<namespace>/<deploymentId>/<branch>/
• Inference endpoints: https://<host>/<deploymentId>/
• Custom actions: https://<host>/<stable-action-name>/

The stable action name is derived from the action's identity (repo, namespace, action name) with a short hash suffix to avoid collisions while keeping names readable and deterministic across redeployments.

#Internal Routing

Inside the cluster, services reach each other via standard Kubernetes DNS:

http://<deployment-name>.<namespace>.svc.cluster.local/

This is used when a space needs to call a linked inference endpoint — the space receives the internal URL as an environment variable, avoiding external roundtrips.

#Git Traffic

Git operations (clone, push, pull) are proxied through an OpenResty/Nginx layer that handles authentication:

1. The user authenticates with a Personal Access Token via HTTP Basic Auth (username:token)
2. OpenResty extracts the Authorization header, logs the username for audit, and forwards the request to GitLab
3. GitLab validates the token and serves the git operation

Git LFS objects are stored in MinIO (S3-compatible object storage) in production. The LFS client resolves pointer files to download URLs via GitLab's LFS API.

#Mutual TLS

Istio enforces mutual TLS between all services in the mesh. Traffic between Themelio Web, the root actors, and GitLab is encrypted and authenticated at the transport layer without application-level changes.

#Environment Domains

Each environment uses its own domain:

The minikube setup uses localtest.me domains, which resolve to 127.0.0.1 without requiring /etc/hosts changes. Docker Compose uses OpenResty as a reverse proxy on ports 80/443.