CXP
Docs
Sign in

Platform setup

These steps happen once per customer, before any agent exists, and they all require a platform administrator. Everything here is shared by every agent in the org, which is the point: rotating a Trigger.dev key later should mean editing one record, not every agent.

1. Create the organization

Go to /organizations/new and create the org. You choose a name and a slug.

The slug is load-bearing. It becomes the first path segment of every URL for this customer — /acme/revenue-chat, /acme/revenue-chat/app — and for zone-backed agents it is compiled into the zone's build. Renaming it later means rebuilding and redeploying every zone in the org. Pick it carefully now.

For this tutorial the slug is acme.

The org slug can be changed later at /acme/settings, which warns you about exactly this and lists the affected agents.

2. Create the Trigger.dev runtime environment

A runtime environment holds the connection details for one Trigger.dev project (or one n8n instance). Multiple agents point at the same environment, so credentials live in one place.

Go to /acme/runtime-environments/new.

Runtime Type — choose Trigger.dev.

Name — required. Use customer + environment, because you will end up with several: Trigger.dev Acme Production.

Trigger.dev API URL — required. https://api.trigger.dev for Trigger.dev Cloud, or your own origin if self-hosted. Private and internal hostnames are rejected outside local development.

Trigger.dev Secret Key — required. From your Trigger.dev project settings; starts with tr_prod_ (or tr_dev_ for a development environment). This is what lets the platform trigger, cancel, poll status, and fetch logs.

Trigger.dev Webhook Secret — required, and this one you cannot invent: Trigger.dev generates it when you create the alert webhook. The form has a collapsible How do I set up the Trigger.dev webhook? panel with the platform's webhook URL ready to copy. Do that step now, in Trigger.dev:

  1. Select the correct Trigger.dev environment (dev / staging / prod) — alerts are per environment.
  2. Open Alerts.
  3. New alert.
  4. Choose Webhook as the delivery method.
  5. Check Run fails.
  6. Paste the platform's URL: https://agents.collectivexp.ai/api/webhooks/trigger-dev.
  7. Copy the generated secret back into this form.

This webhook is how the platform learns about failures it would otherwise only discover by polling. Completion is signalled separately, by the task itself.

Press Create Runtime Environment. The platform tests the connection before saving — a bad URL or key shows an error with a Retry button rather than persisting a broken record. That is a genuine credential check, so if it fails, fix the credentials rather than working around it.

Editing an environment later leaves secret fields blank, meaning keep the current value. Type in a field only when you intend to replace that secret.

3. Create a Nango environment, if you need OAuth

Skip this if every credential your agents need is an API key or basic auth — those go to the platform's own encrypted storage and need nothing extra.

OAuth credentials are managed by Nango, and the connection details live in a runtime environment of type Nango. In this tutorial revenue-chat reads a Google Sheet, so we need one.

At /acme/runtime-environments/new, choose Nango:

  • Nango Host URL — optional. Leave it blank for Nango Cloud.
  • Nango Secret Key — required, from your Nango environment settings.
  • Webhook Signing Key — optional but recommended. Found under Nango's Environment settings → Webhooks. If you leave it blank the platform falls back to the secret key for signature validation.

As with Trigger.dev, the form carries a collapsible setup panel. In Nango:

  1. Select the correct Nango environment.
  2. Environment settings → Webhooks.
  3. Set the Primary URL to https://agents.collectivexp.ai/api/webhooks/nango.
  4. Enable Auth: token refresh error webhooks.
  5. Copy the Signing key into the form.

Without this, a customer's OAuth token can silently go stale and the first symptom is a failed run.

Nango environment selection is per agent, so different agents — and different orgs — can use entirely separate Nango accounts.

4. What you should have now

/acme                              the org
/acme/runtime-environments
  ├── Trigger.dev Acme Production  apiUrl + secretKey + webhookSecret
  └── Nango Acme Production        secretKey + signingKey

Both environments are reusable. When you add a third agent to this org later, it selects these from a dropdown and needs no credentials of its own.

An environment cannot be deleted while any agent still references it — the platform refuses rather than orphaning agents.

A note on doing this per agent instead

The agent form also lets you skip the environment and enter Trigger.dev credentials directly on the agent (Enter credentials manually). It works, and it is fine for a genuine one-off, but it means the secret key is duplicated per agent and rotation becomes a sweep. Prefer a shared environment.

Next

The org is ready.

If any agent will use an OAuth credential, set up the integration next: OAuth integrations with Nango. Otherwise skip straight to Create the agent.