# Self-host App Studio

Deployment prerequisites, verification, and recovery for App Studio.

Source: https://railgrid.ai/docs/self-hosting/providers/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](https://railgrid.ai/docs/self-hosting/providers/) 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](https://railgrid.ai/docs/self-hosting/providers/code/) and [Infrastructure](https://railgrid.ai/docs/self-hosting/providers/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

```bash
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`:

```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
```

```bash
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](https://github.com/railgrid/railgrid/blob/main/providers/app-studio/deploy/chart/README.md).

## 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.

```yaml
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](https://railgrid.ai/docs/self-hosting/providers/#a-fresh-provider-is-unready-until-a-workspace-binds-it). Enable App Studio in a test workspace where Code and Infrastructure are already enabled, then follow the [App Studio quickstart](https://railgrid.ai/docs/use/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](https://github.com/railgrid/railgrid/blob/main/providers/app-studio/deploy/chart/values.yaml) are authoritative for this source baseline. Keep the deployed image and chart versions recorded together.