sovara 0.3.3__tar.gz → 0.3.4__tar.gz

{sovara-0.3.3 → sovara-0.3.4}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: sovara
-Version: 0.3.3
+Version: 0.3.4
 Summary: Python SDK for Sovara agent observability and runtime instrumentation
+Project-URL: Documentation, https://docs.sovara-labs.com
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: dill
@@ -9,6 +10,7 @@ Requires-Dist: flatten_dict
 Requires-Dist: flatten_json
 Requires-Dist: httpx
 Requires-Dist: jsonpickle>=4.1.1
+Requires-Dist: keyring>=25.0.0
 Requires-Dist: pydantic
 Requires-Dist: pyyaml
 Provides-Extra: examples
@@ -47,3 +49,5 @@ with sovara.run("support-agent"):
 The terminal command is distributed separately as the native Sovara CLI. Install
 that CLI for commands such as `sovara record`, `sovara status`, and
 `sovara probe`.
+
+Documentation: https://docs.sovara-labs.com

{sovara-0.3.3 → sovara-0.3.4}/README.md

@@ -27,3 +27,5 @@ with sovara.run("support-agent"):
 The terminal command is distributed separately as the native Sovara CLI. Install
 that CLI for commands such as `sovara record`, `sovara status`, and
 `sovara probe`.
+
+Documentation: https://docs.sovara-labs.com

{sovara-0.3.3 → sovara-0.3.4}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.package-data]
-"sovara.assets" = ["SKILL.md"]
+"sovara.assets" = ["sovara/*.md", "sovara/references/*.md", "sovara/evals/*.json"]
 "sovara.common" = ["*.json"]
 
 [tool.setuptools]
@@ -15,7 +15,7 @@ include = ["sovara*"]
 
 [project]
 name = "sovara"
-version = "0.3.3"
+version = "0.3.4"
 description = "Python SDK for Sovara agent observability and runtime instrumentation"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,6 +26,7 @@ dependencies = [
     "flatten_json",
     "httpx",
     "jsonpickle>=4.1.1",
+    "keyring>=25.0.0",
     "pydantic",
     "pyyaml",
 ]
@@ -38,3 +39,6 @@ examples = [
     "google-genai",
     "claude-agent-sdk",
 ]
+
+[project.urls]
+Documentation = "https://docs.sovara-labs.com"

sovara-0.3.4/src/sovara/assets/sovara/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: sovara
+description: >
+  Use when a user wants to debug, observe, optimize, or capture lessons
+  from a Python or TypeScript LLM agent — recording runs as dataflow
+  graphs of LLM and tool calls, inspecting which step produced a wrong
+  answer, comparing runs to find regressions, annotating failures, or
+  turning recurring lessons into priors that are injected back into
+  context at runtime. Also covers installing the Sovara desktop app,
+  SDK, or CLI, deploying `sovara-server` on Azure with Microsoft
+  Entra auth, or configuring Sovara for Palantir Foundry. Trigger even when the user does not say "Sovara" —
+  phrases like "my agent keeps giving wrong answers", "trace this LLM
+  call", "the agent regressed after my last change", "remember this
+  rule for next time", "inject domain knowledge into my agent at
+  runtime", or "set up observability for my agent" all apply. Do not
+  use for generic prompt engineering with no run inspection, generic
+  HTTP/SQL tracing unrelated to LLM agents, or Azure deployment
+  unrelated to `sovara-server`.
+---
+
+# sovara
+
+## Overview
+
+Sovara helps develop and maintain adaptable agentic systems by recording traces as dataflow graphs and injecting learned priors at runtime.
+
+Core capabilities:
+
+- **Integrated observability**: Record agent traces as dataflow graphs with zero code changes for supported Python workflows.
+- **Priors**: Create, retrieve, validate, and inject reusable lessons into agent context.
+- **SDK install guidance**: Install the desktop app, SDK/runner, CLI, and assistant skill.
+- **Enterprise deploy guidance**: Stand up `sovara-server` on Azure with Microsoft Entra auth.
+- **Palantir setup guidance**: Configure Sovara to use Palantir Foundry as the storage backend and embedding provider.
+
+## Setup Gate
+
+Run project setup checks only for workflows that execute Sovara against a project: recording, probing, logs, annotations, priors, or connecting an agent to a server. Skip this gate when the user only needs SDK/CLI installation guidance or enterprise deployment planning.
+
+For project-scoped workflows:
+
+1. Run `sovara status --path <script-or-project-dir>` before the first project command.
+2. If setup is missing, run `sovara init --project-root <dir> --project-name "<name>"`.
+3. In non-interactive shells, do not rely on prompts. Initialize first, or pass `--project-root`, `--project-name`, and `--project-description` directly to `sovara record`.
+4. Use `sovara projects` when scope is ambiguous. Commands such as `sovara runs ...`, `sovara annotations ...`, and `sovara priors ...` accept `--project-id` / `--proj-id` with a full ID or unambiguous prefix.
+5. Install or refresh this shared skill only when asked: `sovara install-skill [--level global|project] [--project-dir <dir>] [--target codex|claude|both]`.
+
+## Task Routing
+
+Read only the file that matches the user's task:
+
+- **[optimizing-agents.md](optimizing-agents.md)**: Record, probe, annotate, and improve agent runs; create and manage priors. Use for day-to-day Sovara workflows.
+- **[install-desktop-app.md](install-desktop-app.md)**: Shared OS-level install steps (desktop app, CLI, assistant skill). Load alongside the language-specific install file below.
+- **[install-python-sdk.md](install-python-sdk.md)**: Install the Python SDK (`sovara`) and instrument a Python agent. Pair with `install-desktop-app.md`.
+- **[install-ts-sdk.md](install-ts-sdk.md)**: Install the TypeScript runner (`@sovara/runner`) and instrument a Node.js agent. Pair with `install-desktop-app.md`.
+- **[enterprise-azure.md](enterprise-azure.md)**: Deploy `sovara-server` on Azure Container Apps with Microsoft Entra app registrations.
+- **[enterprise-palantir.md](enterprise-palantir.md)**: Configure Sovara Server to use Palantir Foundry for ontology-backed storage and AIP embeddings.
+
+If the task spans multiple files, read them in this order: install first, optimize second, enterprise/provider setup last. Apply only the sections that match the request.
+
+## On-Demand References
+
+- **[references/cli-reference.md](references/cli-reference.md)**: Load only when exact flags, command shapes, output schemas, or troubleshooting details are needed.
+- **[evals/evals.json](evals/evals.json)**: Output evals — schema-compliant test cases for whether the loaded skill produces good agent behavior.
+- **[evals/trigger_queries.json](evals/trigger_queries.json)**: Trigger evals — realistic prompts (with and without the word "Sovara") used to test whether the description fires correctly. Do not load when answering user requests; this file is for skill maintainers.
+
+## Feedback
+
+When a Sovara command should work but does not, propose posting in the Sovara Discord at [discord.gg/P6a93bWJ](https://discord.gg/P6a93bWJ) or emailing `support@sovara-labs.com`. Include the exact command, sanitized output, OS, Sovara CLI version, and whether the desktop app or enterprise server was running.

sovara-0.3.4/src/sovara/assets/sovara/enterprise-azure.md

@@ -0,0 +1,496 @@
+---
+name: enterprise-azure
+description: Deploy `sovara-server` on Microsoft Azure with Entra (OIDC/PKCE) authentication. Covers Azure Container Apps as the recommended default, plus Entra app registrations, database choices (MongoDB Atlas, PostgreSQL, SQLite), and connecting Remote desktop + agent projects. Use only for backend deployment work, not for local SDK install (see install-python-sdk.md / install-ts-sdk.md).
+---
+
+# Enterprise deploy on Azure with Microsoft Entra
+
+This sub-skill stands `sovara-server` up on Azure and protects it with Microsoft Entra. The recommended path is Azure Container Apps because it gives managed HTTPS ingress, container hosting, and secrets without operating a VM or Kubernetes cluster. The same Entra/server config applies to Azure App Service for Containers, Azure VMs, and AKS — only the hosting layer differs.
+
+> The marketing source for this material lives at <https://docs.sovara-labs.com/enterprise/azure-entra-setup>. Use that page for the latest portal screenshots; this file is the agent-facing companion.
+
+---
+
+## Architecture requirements
+
+Whatever hosting model is chosen must provide:
+
+- HTTPS endpoint reachable from user desktops.
+- WebSocket support from the desktop app to the server.
+- Reachability from agent machines that will report runs.
+- Environment-variable or secret configuration for `sovara-server`.
+- Reachable PostgreSQL or MongoDB database for Sovara state.
+- Outbound HTTPS from the server to Microsoft identity endpoints (OIDC/JWKS).
+
+Hosting options:
+
+| Model | Use when | Notes |
+| --- | --- | --- |
+| Azure Container Apps | Simplest managed serverless container deployment | Recommended default |
+| Azure App Service for Containers | Org standardizes on App Service | Same image, env vars, HTTPS, WebSocket |
+| Azure VM | Direct OS / reverse-proxy control | Run image behind Nginx / Caddy / App Gateway |
+| AKS | Org already operates Kubernetes | Standard Deployment, Service, Ingress, secrets |
+
+---
+
+## Prerequisites
+
+- Azure subscription in the Entra tenant where users sign in.
+- Permission to create app registrations in that tenant.
+- Permission to create the selected Azure hosting resources.
+- A reachable PostgreSQL or MongoDB database for Sovara state.
+- Azure CLI installed and authenticated.
+- The published Sovara Server container image tag from Sovara.
+- The Remote desktop app build.
+
+---
+
+## Variables
+
+Choose names before running commands. Container App names must be lowercase, start with a letter, end with a letter or number, and be under 32 characters.
+
+### Common (bash)
+
+```bash
+export TENANT_ID="<tenant-guid>"
+export SUBSCRIPTION_ID="<subscription-guid>"
+export RESOURCE_GROUP="rg-sovara-enterprise"
+export LOCATION="westeurope"
+export CONTAINERAPPS_ENV="sovara-env"
+export CONTAINER_APP_NAME="sovara-server"
+export SERVER_API_APP_NAME="Sovara Server API"
+export DESKTOP_APP_NAME="Sovara Desktop"
+export SOVARA_IMAGE="<published-sovara-server-image>:<version>"
+export REDIRECT_URI="http://localhost/auth/callback"
+```
+
+### Database (pick exactly one)
+
+MongoDB Atlas:
+
+```bash
+export SOVARA_DB_BACKEND="mongodb"
+export SOVARA_MONGODB_URI="mongodb+srv://<user>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority"
+export SOVARA_MONGODB_DB="sovara"
+```
+
+PostgreSQL:
+
+```bash
+export SOVARA_DB_BACKEND="postgresql"
+export SOVARA_PG_DSN="postgresql://<user>:<password>@<host>:5432/sovara"
+```
+
+SQLite is acceptable only for local dev or temporary validation deployments — not for shared production state.
+
+---
+
+## Sign in and select the subscription
+
+```bash
+az login --tenant "$TENANT_ID"
+az account set --subscription "$SUBSCRIPTION_ID"
+az account show --query "{name:name,id:id,tenantId:tenantId,user:user.name}" -o table
+```
+
+Confirm the printed `TenantId` and subscription match. If `az account set` says the subscription does not exist, re-login with the correct tenant.
+
+---
+
+## Create the Entra app registrations
+
+Sovara uses two app registrations:
+
+- **Server API app** — represents `sovara-server`; exposes the `access_as_user` delegated scope.
+- **Desktop app** — public client using PKCE and the loopback redirect URI `http://localhost/auth/callback`. No client secret.
+
+### Server API app
+
+```bash
+SERVER_APP_ID=$(
+  az ad app create \
+    --display-name "$SERVER_API_APP_NAME" \
+    --sign-in-audience AzureADMyOrg \
+    --query appId \
+    -o tsv
+)
+
+SERVER_OBJECT_ID=$(az ad app show --id "$SERVER_APP_ID" --query id -o tsv)
+
+az ad app update \
+  --id "$SERVER_APP_ID" \
+  --identifier-uris "api://$SERVER_APP_ID"
+```
+
+### Expose the `access_as_user` scope
+
+The scope ID must be a GUID. Patch the app manifest through Microsoft Graph:
+
+```bash
+SCOPE_ID=$(uuidgen)
+SCOPE_FILE=$(mktemp)
+
+cat > "$SCOPE_FILE" <<EOF
+{
+  "api": {
+    "requestedAccessTokenVersion": 2,
+    "oauth2PermissionScopes": [
+      {
+        "adminConsentDescription": "Allow Sovara Desktop to access Sovara Server as the signed-in user.",
+        "adminConsentDisplayName": "Access Sovara Server",
+        "id": "$SCOPE_ID",
+        "isEnabled": true,
+        "type": "User",
+        "userConsentDescription": "Allow Sovara Desktop to access Sovara Server as you.",
+        "userConsentDisplayName": "Access Sovara Server",
+        "value": "access_as_user"
+      }
+    ]
+  }
+}
+EOF
+
+az rest \
+  --method PATCH \
+  --uri "https://graph.microsoft.com/v1.0/applications/$SERVER_OBJECT_ID" \
+  --headers "Content-Type=application/json" \
+  --body "@$SCOPE_FILE"
+
+SERVER_SCOPE_ID=$(
+  az ad app show \
+    --id "$SERVER_APP_ID" \
+    --query "api.oauth2PermissionScopes[?value=='access_as_user'].id | [0]" \
+    -o tsv
+)
+```
+
+### Desktop public client app
+
+```bash
+DESKTOP_APP_ID=$(
+  az ad app create \
+    --display-name "$DESKTOP_APP_NAME" \
+    --sign-in-audience AzureADMyOrg \
+    --is-fallback-public-client true \
+    --public-client-redirect-uris "$REDIRECT_URI" \
+    --query appId \
+    -o tsv
+)
+
+az ad app permission add \
+  --id "$DESKTOP_APP_ID" \
+  --api "$SERVER_APP_ID" \
+  --api-permissions "$SERVER_SCOPE_ID=Scope"
+
+az ad sp create --id "$SERVER_APP_ID" >/dev/null
+az ad sp create --id "$DESKTOP_APP_ID" >/dev/null
+```
+
+### Grant admin consent (if required)
+
+For tenants that disallow user consent for delegated scopes:
+
+```bash
+az ad app permission admin-consent --id "$DESKTOP_APP_ID"
+```
+
+---
+
+## Configure server auth env vars
+
+Every hosting model must pass these env vars to `sovara-server`:
+
+```text
+SOVARA_AUTH_MODE=enterprise
+SOVARA_ENTRA_TENANT_ID=<tenant-guid>
+SOVARA_OIDC_ISSUER=https://login.microsoftonline.com/<tenant-guid>/v2.0
+SOVARA_OIDC_AUDIENCE=<server-api-client-id>
+SOVARA_OIDC_REQUIRED_SCOPE=access_as_user
+SOVARA_DESKTOP_CLIENT_ID=<desktop-client-id>
+SOVARA_DESKTOP_SCOPES=api://<server-api-client-id>/access_as_user
+```
+
+The container listens on `0.0.0.0:5959`. The Azure hosting layer terminates HTTPS and forwards to port `5959`.
+
+---
+
+## Configure database and storage
+
+Sovara persists projects, memberships, agent tokens, runs, annotations, priors, and model settings.
+
+Configure the database at deployment time. Do **not** store the MongoDB URI or PostgreSQL DSN in the desktop app or in normal project settings.
+
+### MongoDB Atlas (recommended first MongoDB path)
+
+1. Create or select an Atlas project.
+2. Create a cluster on **Microsoft Azure** in the same region as `sovara-server` if possible.
+3. Create a database user with read/write on the `sovara` database.
+4. In **Network Access**, allow the Sovara Server hosting environment. `0.0.0.0/0` is fine for validation; replace with Atlas private networking or a stable Azure outbound IP allowlist before production.
+5. Copy the `mongodb+srv://...` connection string from the cluster **Connect** flow.
+6. Substitute the real username/password into that string.
+7. Set `SOVARA_MONGODB_URI` to the full string and `SOVARA_MONGODB_DB=sovara`.
+
+For an existing Container App, update the secret and revision after rotating credentials:
+
+```bash
+az containerapp secret set \
+  --resource-group "$RESOURCE_GROUP" \
+  --name "$CONTAINER_APP_NAME" \
+  --secrets mongodb-uri="$SOVARA_MONGODB_URI"
+
+az containerapp update \
+  --resource-group "$RESOURCE_GROUP" \
+  --name "$CONTAINER_APP_NAME" \
+  --set-env-vars \
+    SOVARA_DB_BACKEND=mongodb \
+    SOVARA_MONGODB_URI=secretref:mongodb-uri \
+    SOVARA_MONGODB_DB="$SOVARA_MONGODB_DB"
+```
+
+Updating a secret does not restart running revisions. After a rotation:
+
+```bash
+ACTIVE_REVISION=$(
+  az containerapp revision list \
+    --resource-group "$RESOURCE_GROUP" \
+    --name "$CONTAINER_APP_NAME" \
+    --query "[?properties.trafficWeight==\`100\`].name | [0]" \
+    -o tsv
+)
+
+az containerapp revision restart \
+  --resource-group "$RESOURCE_GROUP" \
+  --name "$CONTAINER_APP_NAME" \
+  --revision "$ACTIVE_REVISION"
+```
+
+### PostgreSQL
+
+```text
+postgresql://<user>:<password>@<host>:5432/sovara
+```
+
+For a new Container App use `--secrets pg-dsn=...` in the create command and set `SOVARA_PG_DSN=secretref:pg-dsn`. For an existing app:
+
+```bash
+az containerapp secret set \
+  --resource-group "$RESOURCE_GROUP" \
+  --name "$CONTAINER_APP_NAME" \
+  --secrets pg-dsn="$SOVARA_PG_DSN"
+
+az containerapp update \
+  --resource-group "$RESOURCE_GROUP" \
+  --name "$CONTAINER_APP_NAME" \
+  --set-env-vars \
+    SOVARA_DB_BACKEND=postgresql \
+    SOVARA_PG_DSN=secretref:pg-dsn
+```
+
+---
+
+## Deploy on Azure Container Apps
+
+### Resource group + Container Apps environment
+
+```bash
+az extension add --name containerapp --upgrade
+az provider register --namespace Microsoft.App
+az provider register --namespace Microsoft.OperationalInsights
+
+az group create \
+  --name "$RESOURCE_GROUP" \
+  --location "$LOCATION"
+
+az containerapp env create \
+  --name "$CONTAINERAPPS_ENV" \
+  --resource-group "$RESOURCE_GROUP" \
+  --location "$LOCATION"
+```
+
+### Create the Container App
+
+The published container listens on `5959`. Azure Container Apps gives it a public HTTPS endpoint:
+
+```bash
+az containerapp create \
+  --name "$CONTAINER_APP_NAME" \
+  --resource-group "$RESOURCE_GROUP" \
+  --environment "$CONTAINERAPPS_ENV" \
+  --image "$SOVARA_IMAGE" \
+  --ingress external \
+  --target-port 5959 \
+  --cpu 0.5 \
+  --memory 1.0Gi \
+  --min-replicas 1 \
+  --max-replicas 1 \
+  --secrets mongodb-uri="$SOVARA_MONGODB_URI" \
+  --env-vars \
+    SOVARA_AUTH_MODE=enterprise \
+    SOVARA_ENTRA_TENANT_ID="$TENANT_ID" \
+    SOVARA_OIDC_ISSUER="https://login.microsoftonline.com/$TENANT_ID/v2.0" \
+    SOVARA_OIDC_AUDIENCE="$SERVER_APP_ID" \
+    SOVARA_OIDC_REQUIRED_SCOPE=access_as_user \
+    SOVARA_DESKTOP_CLIENT_ID="$DESKTOP_APP_ID" \
+    SOVARA_DESKTOP_SCOPES="api://$SERVER_APP_ID/access_as_user" \
+    SOVARA_DB_BACKEND=mongodb \
+    SOVARA_MONGODB_URI=secretref:mongodb-uri \
+    SOVARA_MONGODB_DB="$SOVARA_MONGODB_DB"
+```
+
+### Get the server URL
+
+```bash
+SERVER_FQDN=$(
+  az containerapp show \
+    --name "$CONTAINER_APP_NAME" \
+    --resource-group "$RESOURCE_GROUP" \
+    --query properties.configuration.ingress.fqdn \
+    -o tsv
+)
+
+SERVER_URL="https://$SERVER_FQDN"
+echo "$SERVER_URL"
+```
+
+## Verify the server
+
+```bash
+curl -fsS "$SERVER_URL/health"
+curl -fsS "$SERVER_URL/auth/config"
+```
+
+`/auth/config` should respond with:
+
+```json
+{
+  "auth_mode": "enterprise",
+  "provider": "entra",
+  "tenant_id": "<tenant-guid>",
+  "desktop_client_id": "<desktop-client-id>",
+  "scopes": ["api://<server-api-client-id>/access_as_user"],
+  "server_audience": "<server-api-client-id>"
+}
+```
+
+---
+
+## Connect the Remote desktop app
+
+1. Open the Remote desktop app.
+2. Enter the server HTTPS URL.
+3. Click **Connect**.
+4. Click **Sign in with Microsoft** and complete the browser login.
+5. Confirm the desktop app shows the Entra profile.
+6. Create a project — the creator becomes project admin.
+
+---
+
+## Connect an agent project
+
+From the project's settings in the Remote desktop app, create an agent token. Then on the agent machine:
+
+```bash
+sovara connect-agent \
+  --project-root /path/to/agent/project \
+  --server-url "$SERVER_URL" \
+  --project-id "<project-id>" \
+  --agent-token "<agent-token>"
+```
+
+After this one-time pairing, run the agent normally. Recorded runs appear in the project without the runner sending a user ID. For SDK install on the agent side, see [install-python-sdk.md](install-python-sdk.md) or [install-ts-sdk.md](install-ts-sdk.md).
+
+---
+
+## Access model
+
+The Entra token only proves identity. Project access still comes from the Sovara database:
+
+- Project creators become `admin`.
+- Admins add members and create agent tokens.
+- Editors and viewers cannot create agent tokens.
+- Agent tokens can only write runs to their bound project.
+
+Adding a member by email or user ID requires that the user has signed in at least once, so their Entra identity exists in Sovara. Directory-wide user search is not part of this setup because it requires Microsoft Graph permissions and admin consent.
+
+---
+
+## Troubleshooting
+
+### `az account set` cannot find the subscription
+
+```bash
+az account list --query "[].{name:name,id:id,tenantId:tenantId,isDefault:isDefault}" -o table
+az login --tenant "$TENANT_ID"
+```
+
+If the subscription still doesn't appear, the signed-in user lacks access to it in this tenant.
+
+### App registration creation fails
+
+The tenant likely blocks user app registrations. Ask an Entra admin to run those steps or grant the permission temporarily.
+
+### Desktop login: redirect URI mismatch
+
+- The Desktop app registration must be a public client/native app.
+- It must have `http://localhost/auth/callback` as a redirect URI.
+- `SOVARA_DESKTOP_CLIENT_ID` must be the Desktop app client ID, not the Server API app client ID.
+
+### Desktop login: invalid audience or scope
+
+- `SOVARA_OIDC_AUDIENCE` must equal the Server API app client ID.
+- `SOVARA_DESKTOP_SCOPES` must equal `api://<server-api-client-id>/access_as_user`.
+- The Desktop app must have the delegated `access_as_user` permission for the Server API app.
+- If tenant policy requires it, admin consent must be granted.
+
+### Desktop cannot load `/auth/config`
+
+```bash
+curl -v "$SERVER_URL/auth/config"
+```
+
+Check server URL, HTTPS ingress, container startup, and any network policy between desktop and Azure.
+
+### MongoDB connection fails
+
+Read the Container App logs first. Common causes:
+
+- `Authentication failed` — bad Atlas user/password in `mongodb-uri`. Rotate and restart the active revision.
+- `ServerSelectionTimeoutError` / connection timeout — Atlas IP access list or private networking blocks the outbound connection.
+- `Cannot specify multiple hosts with directConnection=true` — the server image is too old for Atlas SRV URIs. Use a newer image.
+
+For validation, `0.0.0.0/0` in the Atlas IP access list isolates DB/credentials issues; tighten before production.
+
+### Inspect Container App logs
+
+```bash
+az containerapp logs show \
+  --name "$CONTAINER_APP_NAME" \
+  --resource-group "$RESOURCE_GROUP" \
+  --follow
+```
+
+### Inspect Container App env vars
+
+```bash
+az containerapp show \
+  --name "$CONTAINER_APP_NAME" \
+  --resource-group "$RESOURCE_GROUP" \
+  --query "properties.template.containers[0].env" \
+  -o table
+```
+
+---
+
+## Clean up and retry
+
+Only clean up Azure resources when the user explicitly asks to start over or remove the deployment. Treat this as destructive: first print the resolved resource group, subscription, tenant, Desktop app ID, and Server API app ID; then ask for explicit confirmation before running delete commands.
+
+After confirmation, delete the resource group and both app registrations:
+
+```bash
+az group delete --name "$RESOURCE_GROUP" --yes
+az ad app delete --id "$DESKTOP_APP_ID"
+az ad app delete --id "$SERVER_APP_ID"
+```
+
+If the Remote desktop app remembers an old backend, replace it in remote connection settings. If an agent project still points at an old backend, rerun `sovara connect-agent` from the new project settings.