# Manage apps

An **app** represents a workload inside a [Catalyst project](https://docs.diagrid.io/operate/platform-operations/projects). 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](https://docs.diagrid.io/develop/connect) guide walks through how apps fit into the broader connection model.

:::tip 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](https://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

```bash
# 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 \
  --endpoint https://myendpoint.io \
  --endpoint-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`](https://docs.diagrid.io/references/catalyst/cli-reference/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 `--endpoint` on [`diagrid app create`](https://docs.diagrid.io/references/catalyst/cli-reference/app/create) / [`update`](https://docs.diagrid.io/references/catalyst/cli-reference/app/update). |
| **Connect via private tunnel** | You are running the app locally for development. | [`diagrid dev run`](https://docs.diagrid.io/references/catalyst/cli-reference/dev/run) `--id my-app --app-port 9001` |
| **Connect to terminal** | You want to inspect inbound traffic without running app code. | [`diagrid listen`](https://docs.diagrid.io/references/catalyst/cli-reference/listen) `--id my-app` |

See [Connect for Dev/Test](https://docs.diagrid.io/develop/local-development/catalyst-cli) 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:

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

See [`diagrid app update`](https://docs.diagrid.io/references/catalyst/cli-reference/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.

:::tip Combine with network allowlisting

For production deployments, pair the application token with network-level allowlisting using the [project's egress address](https://docs.diagrid.io/operate/platform-operations/projects#inspect-a-project) 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:

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

```bash
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](https://docs.diagrid.io/operate/plans-and-support#plan-limits) for the request-rate limits of each plan.

## Inspect apps

```bash
# 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`](https://docs.diagrid.io/references/catalyst/cli-reference/app/list), [`diagrid app get`](https://docs.diagrid.io/references/catalyst/cli-reference/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

```bash
# 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`](https://docs.diagrid.io/references/catalyst/cli-reference/app/update), and [`diagrid app delete`](https://docs.diagrid.io/references/catalyst/cli-reference/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](https://docs.diagrid.io/develop/workflows).
- **Agents** — agents leverage Dapr APIs for state, pub/sub, and service invocation. See [Develop Agents](https://docs.diagrid.io/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](https://docs.diagrid.io/develop/dapr-apis).

## Declarative management

Apps can be managed declaratively with [`diagrid apply`](https://docs.diagrid.io/references/catalyst/cli-reference/apply):

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

```bash
diagrid apply -f my-appid.yaml
```

See [Declarative management](https://docs.diagrid.io/operate/project-operations/declarative-management) for the full GitOps workflow, `diagrid export` patterns, and scoped API keys for CI.

## What's next

- [Components](https://docs.diagrid.io/operate/project-operations/components) — wire backing infrastructure to apps.
- [Connect to Catalyst](https://docs.diagrid.io/develop/connect) — understand how apps fit into the overall connectivity model.
- [Observability](https://docs.diagrid.io/operate/project-operations/observability) — inspect app metrics, logs, and API calls.