Skip to main content

Operator quickstart

After installing Catalyst, create a governed project that a team can safely build in. This guide covers the common operations you perform as a platform operator, walking that journey end to end with the diagrid CLI: create a project, create the team's workload identities, wire up infrastructure, make it resilient, lock it down with zero-trust controls, and hand it over.

Each step is a command you can run. Every step also has an equivalent in the Catalyst console and a declarative form you can keep in Git.

What you'll build​

By the end of this guide you'll have a project with App IDs, scoped infrastructure, resiliency policies, access controls, trace export, and project-scoped team access.

Before you begin​

# Authenticate the CLI to your Catalyst organization
diagrid login

1. Create a project for a team​

A project is the isolation boundary you hand to a team or environment. Create a project, then enable only the managed infrastructure required by the workloads that will run in it, and set it as your default so every project-scoped command that follows runs within it:

# Create a project and set it as the default for later commands
diagrid project create payments --enable-agent-infrastructure --use

Provision the managed infrastructure that matches what the team runs:

  • Applications — add --deploy-managed-pubsub and --deploy-managed-kv for Catalyst-hosted Pub/Sub and key-value stores.
  • Workflow applications — add --enable-managed-workflow for the managed workflow store.
  • Agents — add --enable-agent-infrastructure, which provisions Pub/Sub, key-value, workflow, and the agent registry in one step.
  • MCP servers — no managed infrastructure needed. The project simply routes MCP and service-invocation calls between workloads, acting as a secure gateway.

See Projects for the full set of project options.

2. Create workload identities​

Every workload — an application, an agent, or an MCP server — needs an App ID, its identity inside the project. The App ID does two jobs: it lets the workload connect to Catalyst, authenticating every API call it makes, and it is the handle you scope security to — components, access policies, and resiliency all bind to App IDs. Create them first, so you can scope infrastructure and policies to them in the next steps:

# An application
diagrid appid create orders-api

# An agent
diagrid appid create billing-agent

# An MCP server
diagrid appid create github-mcp

To connect code to the project, the team needs two things: the project's endpoints (shared by every App ID) and each App ID's API token. Retrieve them and share them securely:

# Project HTTP and gRPC endpoints
diagrid project get payments

# An App ID's API token
diagrid appid get orders-api

The team sets these as the DAPR_HTTP_ENDPOINT, DAPR_GRPC_ENDPOINT, and DAPR_API_TOKEN environment variables. — see Connect to Catalyst. For dev/test, diagrid dev run injects them automatically. For day-2 operations on App IDs, see App IDs.

3. Connect backing infrastructure​

Managed services cover Pub/Sub, key-value, and workflow. To wire in infrastructure you operate — your Redis, Postgres, or Kafka, whether it runs on-premises or in a cloud — create a component. The component abstracts that infrastructure and decouples it from your application: the workload calls a standard Dapr API while Catalyst routes the call to whatever the component points at, so you can swap the backing store without changing application code. Scope it to the App IDs that may use it:

# Register your Redis as a state store, usable only by the orders-api App ID
diagrid component create orders-state \
  --type state.redis \
  --metadata redisHost=my-redis.internal:6379 \
  --metadata redisPassword=<password> \
  --scopes orders-api

See Components for the full catalog of supported component types.

4. Make application and infrastructure interactions resilient​

A resiliency policy tells Catalyst how to recover from transient failures — timeouts, retries, and circuit breakers — on calls to other apps and to components, with no application code changes. Define it in a YAML manifest and list the targets it applies to. For example, retry calls to orders-api up to three times, five seconds apart:

# orders-resiliency.yaml
apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
  name: orders-resiliency
spec:
  policies:
    retries:
      defaultRetry:
        policy: constant
        duration: 5s
        maxRetries: 3
  targets:
    apps:
      orders-api:
        retry: defaultRetry

Apply it with the CLI:

# Create the resiliency policy from the manifest
diagrid resiliency create -f orders-resiliency.yaml

See Apply resiliency policies for timeouts, circuit breakers, and component targets.

5. Bring your own secret store​

By default, Catalyst manages secrets for you: when you create a component, endpoint, or configuration, it extracts the sensitive fields — passwords, tokens, keys — into a built-in managed secret store and replaces them with references, so plaintext is never stored in the control plane. No setup required.

If your organization already keeps credentials in AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault, bring it instead. Register it as a secretstores component, and Catalyst resolves secret references through it at runtime:

# Register your own HashiCorp Vault as a secret store
diagrid component create team-vault \
  --type secretstores.hashicorp.vault \
  --metadata vaultAddr=https://vault.internal:8200 \
  --metadata vaultToken=<token> \
  --scopes orders-api

The managed store and your own can coexist. See Manage secrets.

6. Lock it down with zero trust​

Catalyst gives you project-level isolation by default — the workloads and resources inside a project can reach one another, while everything outside it is denied. From there you tighten access at the workload, component, topic, and workflow levels with these controls:

  • Scope every component to a single App ID. List one App ID in the component's scopes and only that workload can use it — every other App ID in the project is denied the infrastructure behind it:

    diagrid component create orders-state --type state.redis --scopes orders-api

  • Lock down access between workloads. Attach a deny-by-default access policy to a target App ID and allow-list only its expected callers; any other App ID that tries to invoke it is rejected before the call reaches it. This is also how you secure an MCP server (see service invocation and MCP access policies):

    diagrid configuration create github-mcp-acl --default-action deny --policy billing-agent:allow
    diagrid appid update github-mcp --app-config github-mcp-acl

  • Scope pub/sub topics. On the pub/sub component, publishingScopes limits which topics each App ID may publish to and subscriptionScopes limits which it may subscribe from; anything outside those lists is blocked. Here orders-api may only publish to orders, and billing-agent may only subscribe to it:

    # orders-pubsub.yaml
    apiVersion: cra.diagrid.io/v1beta1
    kind: Component
    metadata:
      name: orders-pubsub
    spec:
      type: pubsub.redis
      version: v1
      metadata:
        - name: redisHost
          value: "my-redis.internal:6379"
        - name: publishingScopes
          value: "orders-api=orders"
        - name: subscriptionScopes
          value: "billing-agent=orders"
    scopes:
      - orders-api
      - billing-agent

  • Lock down cross-application workflows. Allow-list which App IDs may schedule workflows and activities on a workflow application; a caller that isn't listed is rejected with a PermissionDenied error (see workflow access policies):

    diagrid workflow access-policy create orders-workflow-policy --scopes orders-api --callers billing-agent

  • Sign workflow history. Catalyst cryptographically signs each step it records, so a workflow's history cannot be altered after the fact — giving you a verifiable, provable record of exactly what ran. It can only be enabled at project creation:

    diagrid project create payments --enable-agent-infrastructure --enable-workflow-history-signing --use

Together these give you defense in depth across identity, access, messaging, and execution. For the bigger picture, read Zero-trust security for distributed applications with Dapr.

7. Export traces to your observability backend​

Out of the box, Catalyst gives you metrics, API logs, and the apps graph for every workload — no setup required. If you also run a centralized tracing backend, you can export distributed traces to any OpenTelemetry (OTLP) collector — Grafana Tempo, Jaeger, Datadog, or your own — so Catalyst traffic shows up alongside the rest of your telemetry. Create a Configuration for trace export and attach it to the App IDs whose traces you want to export:

# Create a configuration that exports traces to your OpenTelemetry collector
diagrid configuration create otel-export \
  --tracing-sampling-rate 1 \
  --tracing-otel-endpoint otel-collector.observability:4317 \
  --tracing-otel-protocol grpc

# Attach it to an App ID
diagrid appid update orders-api --app-config otel-export

For a secured collector, add --tracing-otel-secure and --tracing-otel-header 'Authorization:Bearer <token>'. A single Configuration can combine tracing with access control, so attach one per App ID.

8. Hand the project off​

The project is now a secure, ready-to-use space. Give the team access by adding users with a role scoped to this project. The role decides what each person can do:

  • Admin — full control of the project: create and change App IDs, components, and policies. Give this to the team that owns the project.

    diagrid user create --email lead@example.com --name "Team lead" --role cra.diagrid:admin:projects:payments

  • Viewer — read-only access to every resource, with no ability to change anything. Good for support staff or auditors.

    diagrid user create --email support@example.com --name "Support" --role cra.diagrid:viewer:projects:payments

Roles in between — such as cra.diagrid:editor — grant create and update access without full admin rights. See Manage access for the full role matrix, organization-wide roles, SSO, and API keys for automation.

The team then connects applications and agents (see Connect to Catalyst) and creates any additional App IDs and workloads. From there you operate and observe everything in one place: workflows, agents, and metrics, API logs, and the apps graph.

Manage Catalyst as code​

Every command above has a declarative equivalent. Keep your projects, components, App IDs, and policies as YAML in Git and apply them with a single upsert command that works for any resource kind:

# Create or update any resource (project, component, App ID, policy) from YAML
diagrid apply -f payments-project.yaml

Use diagrid export to capture existing resources as YAML, and wire diagrid apply into CI/CD for GitOps. See Declarative management.

Last updated on