Manage apps

An app represents a workload inside a Catalyst project. Think of it like a username and password pair: the app's name identifies your workload, and its API token authenticates every Dapr API call it makes to Catalyst. Each app also optionally configures how Catalyst routes traffic back to your app — pub/sub messages, input bindings, service invocations, actor invocations, and health checks.

Whether you're running a workflow, a durable agent, or a microservice, each workload runs as an app for identity, connectivity, and component scoping. The Connect to Catalyst guide walks through how apps fit into the broader connection model.

Manage from the Catalyst console

Every operation on this page — creating apps, configuring app connections, health checks, body-size limits, and deleting — can also be done from the Catalyst Web UI at catalyst.diagrid.io.

What an app provides

Each app exposes:

API token — a bearer token used by your application to authenticate every Dapr API call to Catalyst.
App connection (optional) — how Catalyst reaches your application for inbound requests, via a reachable endpoint URL, a private tunnel, or streamed to the terminal.
Health checks — optional HTTP health probes against your application, with configurable path, interval, timeout, and failure threshold.
Runtime configuration — body-size limits, app protocol (HTTP or gRPC), channel timeouts, and an optional application token for securing callbacks.
Component scope — the set of components (state stores, pub/subs, bindings, etc.) that this app can use.

Create an app

# App ID without a reachable endpoint — good for apps that only call Catalyst APIs (e.g., workflow clients)
diagrid app create my-appid --project my-project --wait

# App ID with a reachable app endpoint and an application token for callbacks
diagrid app create my-subscriber \
  --project my-project \
  --endpoint https://myapp.myorg.com/ \
  --endpoint-token xxxxxxxx \
  --wait

# App ID with a custom health check
diagrid app create my-api \
  --app-endpoint https://myendpoint.io \
  --app-protocol http \
  --enable-app-health-check=true \
  --app-health-check-path "/healthz" \
  --app-health-probe-interval 5 \
  --app-health-probe-timeout 500 \
  --app-health-threshold 5 \
  --wait

# App ID with an increased max body size (default is the project-level value)
diagrid app create my-large-payload-app --max-body-size 8Mi --wait

See diagrid app create for the complete list of flags.

Connection options

When Catalyst needs to call your application (to deliver a pub/sub message, fire an input binding, respond to a service invocation, or invoke an actor), it routes the request through the app connection. Choose the option that matches where your app runs — a reachable URL for production, a tunnel for local development, or streaming to your terminal for inspection:

Option	Use when	CLI
Connect to app endpoint	Your app is reachable over the network (public HTTPS, private endpoint).	Set `--app-endpoint` on `diagrid app create` / `update`.
Connect via private tunnel	You are running the app locally for development.	`diagrid dev run` `--app-id my-app --app-port 9001`
Connect to terminal	You want to inspect inbound traffic without running app code.	`diagrid listen` `--app-id my-app`

See Connect for Dev/Test for the full local-development workflow.

Secure the application connection

When you configure a reachable app endpoint, secure the callback with an application token so only Catalyst can call your app:

diagrid app update my-subscriber \
  --endpoint-token "$(openssl rand -hex 32)"

See diagrid app update for all updatable fields. Catalyst includes the token in the dapr-api-token HTTP header (or gRPC metadata) for every request it makes to your application. Validate the token in your app code and reject any request that doesn't carry it.

Combine with network allowlisting

For production deployments, pair the application token with network-level allowlisting using the project's egress address so that only Catalyst can route traffic to your app.

Health checks

Catalyst can monitor your application's health and stop routing traffic to unhealthy instances:

diagrid app update my-api \
  --enable-app-health-check=true \
  --app-health-check-path "/healthz" \
  --app-health-probe-interval 5 \
  --app-health-probe-timeout 500 \
  --app-health-threshold 3

--app-health-probe-interval controls how often (in seconds) Catalyst probes the endpoint.
--app-health-probe-timeout sets the probe timeout in milliseconds.
--app-health-threshold is the number of consecutive failures before the app is considered unhealthy.

Body-size and channel limits

Each app inherits project-level limits for request body size and channel timeout. Override them per app when a workload has different requirements:

diagrid app update my-upload-api \
  --max-body-size 16Mi \
  --app-channel-timeout-seconds 120

Apps default to a 4Mi maximum body size. See Plans & Support for the rest of the networking limits.

Inspect apps

# List all App IDs in the active project
diagrid app list

# Get details for a specific App ID, including its API token and endpoints
diagrid app get my-appid

# Stream logs from the App ID's Dapr runtime
diagrid appid logs my-appid --follow

See diagrid app list, diagrid app get, and diagrid appid logs. The logs command streams Dapr runtime logs from the Catalyst data plane so you can debug startup errors, component binding failures, and callback issues without leaving the terminal.

Update and delete apps

# Interactively edit an App ID's specification
diagrid appid edit my-appid

# Update a specific field
diagrid app update my-appid --endpoint https://my-new-endpoint/

# Delete an App ID (this removes its API token and all component bindings)
diagrid app delete my-appid --wait

See diagrid appid edit, diagrid app update, and diagrid app delete.

Use with workflows, agents, and distributed apps

Workflows — each workflow execution authenticates with an app's API token when calling the Workflow API. See Develop Durable Workflows.
Agents — agents leverage Dapr APIs for state, pub/sub, and service invocation. See Develop Agents.
Distributed applications — each microservice gets its own app, and services invoke one another by app name through the Service Invocation API. See the Dapr APIs guide.

Declarative management

Apps can be managed declaratively with diagrid apply:

apiVersion: cra.diagrid.io/v1beta1
kind: AppIdentity
metadata:
  name: my-appid
spec:
  appEndpoint:
    url: https://myapp.myorg.com/
  protocol: http
  healthCheck:
    path: /healthz
    probe:
      enabled: true
  maxBodySize: 8Mi

diagrid apply -f my-appid.yaml

See Declarative management for the full GitOps workflow, diagrid export patterns, and scoped API keys for CI.

What's next

Components — wire backing infrastructure to apps.
Connect to Catalyst — understand how apps fit into the overall connectivity model.
Observability — inspect app metrics, logs, and API calls.

What an app provides​

Create an app​

Connection options​

Secure the application connection​

Health checks​

Body-size and channel limits​

Inspect apps​

Update and delete apps​

Use with workflows, agents, and distributed apps​

Declarative management​

What's next​