Self-host App Studio

Prerequisites

You need a Kubernetes runtime you administer, Helm, network access from the provider runtime to the hub and advertised virtual-workspace endpoints, and permission to onboard this provider. Use the common provider flow to obtain the workspace kubeconfig. The examples below use a Secret named railgrid-provider-kubeconfig with data key kubeconfig.

App Studio also needs:

• A Postgres database for messages, projects, and runs. The chart does not provision it.
• The Code and Infrastructure providers installed; App Studio can only be enabled in a workspace that has both enabled.
• The hub’s public URL, reachable from the provider pod and from sandboxes.

Install

kubectl create namespace railgrid-provider-app-studio
kubectl --namespace railgrid-provider-app-studio create secret generic railgrid-provider-kubeconfig \
  --from-file=kubeconfig=./app-studio.kubeconfig
kubectl --namespace railgrid-provider-app-studio create secret generic app-studio-db \
  --from-literal=database-url='postgres://USER:PASSWORD@HOST:5432/app_studio?sslmode=require'

app-studio-values.yaml:

hub:
  url: https://railgrid-hub.railgrid-system.svc.cluster.local:9443
  tokenSecretRef:
    name: ""
  # Browser-reachable origin for preview authorization and browser handoffs.
  publicURL: https://console.example.com
  # Public origin action-enabled development runtimes call back to.
  actionsExternalURL: https://console.example.com
catalogEntry:
  enabled: true
store:
  databaseURLSecretRef:
    name: app-studio-db       # key database-url
workspace:
  persistence:
    enabled: true
    size: 1Gi

helm upgrade --install app-studio oci://ghcr.io/railgrid/charts/railgrid-app-studio-provider \
  --version CHART_VERSION --namespace railgrid-provider-app-studio --values app-studio-values.yaml

The chart README contains the matching values table for the deployed version: chart instructions .

Provider requirements

Two hub URLs. hub.url is the internal provider-to-hub route. hub.publicURL and hub.actionsExternalURL are what a browser or a sandbox reaches; private preview inspection fails closed when publicURL is unset or invalid.

Sandbox trust for the public hub. Action-enabled development sandboxes exchange tokens with hub.actionsExternalURL, and their image ships no system trust store. If the public certificate chains to a root the sandbox cannot verify, mount the public CA chain through hub.actionsCABundleConfigMap: Railgrid’s production uses the Google Trust Services roots behind its Google-managed certificate; its development environment uses the ISRG roots behind Let’s Encrypt. The ConfigMap augments trust; it never replaces it.

hub:
  actionsCABundleConfigMap:
    name: app-studio-actions-ca
    key: ca-bundle.pem

Replicas. The chart defaults to one replica; browser session ownership is process-local. Newer charts forward project requests between replicas over internalPort. Check the README of the chart version you deploy before raising replicaCount.

Workspace storage. Project files, including projects without Git, live on the workspace volume. The default PVC keeps them across pod replacement; workspace.emptyDir: true loses local source on every replacement and is for disposable projects only. Changing values does not migrate files; follow the chart README’s upgrade procedure before switching storage.

Spend limits. assistant.limits.orgMonthlyUSDCap (default 100 USD per organization per month), maxIterations, and rolloutBudgetTokens bound model usage. Never disable them for untrusted tenants.

Verify

Run kubectl -n railgrid-provider-app-studio get pods and wait for Ready and a fresh heartbeat. A fresh provider stays unready until a workspace enables it; see the common flow . Enable App Studio in a test workspace where Code and Infrastructure are already enabled, then follow the App Studio quickstart through a published preview.

Recover

For a failed upgrade, preserve project and message data, inspect pod events and logs, and restore Postgres before retrying. Verify credentials, provider bindings, and a disposable preview before returning the provider to users. A preview that loads but cannot be inspected privately points at hub.publicURL; a sandbox that cannot reach the hub points at hub.actionsExternalURL or its CA bundle.

Configuration reference

Chart values are authoritative for this source baseline. Keep the deployed image and chart versions recorded together.