> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ellaworks.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ellaworks.ai/_mcp/server.

# Environment Setup

This guide walks you through setting up the core building blocks of Ellaworks: a prompt registry, an environment, and optionally a fleet and LLM provider. By the end you'll have a working foundation for versioning and deploying prompts.

## Set up a Prompt Registry

A registry is where your versioned prompt artifacts live — think of it as a package repository scoped to your organization.

> **Note**
>
> Registries, environments, and secrets are managed by organization owners and admins. Other members don't see these pages in the sidebar.

#### Navigate to Registries

From your organization dashboard, click **Registries** in the sidebar (under **Assets**).

![Navigate to the Registries page](/_fern-img/53d63e2f0e85c2ffcd982bf28dc33eb4c556533d9e20f3a66b0646e4d0b8de7c.webp)

#### Create a new registry

Click **New registry** and fill in:

* **Visibility** — choose **Public** or **Private**
* **Registry Name** — letters, numbers, dots, underscores, and hyphens only (e.g. `production-prompts`)

Then click **Create Registry**.

![Create a new registry](/_fern-img/2f666ff1ef608fafd8fe283f61ce60ad41974513135067a1cb68ef6335d7ed1b.webp)

### Public vs Private Registries

|                | Public                                                         | Private                                                                     |
| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Access**     | Anyone on the internet can pull prompts without authentication | Restricted to org members and API keys from your organization               |
| **Use case**   | Open-source prompts, community templates, shared examples      | Proprietary prompts, internal agent logic, production systems               |
| **API access** | No API key header required                                     | Requires `X-API-Key` or `Authorization: Bearer` (see [API Keys](/api-keys)) |

Prompts are pulled from `/api/prompts/{org-slug}/{registry-name}/{prompt-name}/{version}`, with an optional `model` query parameter (defaults to `generic`).

**Accessing a public registry** — no authentication needed:

```bash
curl "https://app.ellaworks.ai/api/prompts/your-org/public-prompts/greeting/1.0.0?model=generic"
```

**Accessing a private registry** — requires an API key from the registry's organization (`X-API-Key` or `Authorization: Bearer`; if both are sent, `X-API-Key` wins):

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.ellaworks.ai/api/prompts/your-org/internal-prompts/greeting/1.0.0?model=generic"
```

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.ellaworks.ai/api/prompts/your-org/internal-prompts/greeting/1.0.0?model=generic"
```

> **Note**
>
> Public registries are great for sharing prompt templates with the community or across teams. Use private registries for anything you don't want exposed outside your organization. Requests for a private registry without valid access return `404 Not found`, so the registry's existence isn't revealed.

## Add an Environment

Environments let you isolate provider credentials, variables, and configuration per deployment stage. A typical setup includes `development`, `staging`, and `production` environments.

Every organization also has a **Global** environment, created automatically. Its variables and provider credentials are the base for every other environment; an individual environment only needs to define the values it overrides.

#### Navigate to Environments

Click **Environments** in the sidebar (under **Delivery**).

![Navigate to the Environments page](/_fern-img/1e2b8fae8cd6cbe06f6b211afd873bce6bdb1fa5d2baf74488287e2ec66821b5.webp)

#### Create an environment

Click **Create Environment** and give it a **Name** (e.g. `development`). The name `*` is reserved for the Global environment.

![Create a new environment](/_fern-img/07a542a6e5390036e200dcebbe4891a6810b304e3e2898cd9adad76e67b24dd4.webp)

#### Configure a provider

Under **Providers**, select a deployment provider, click **Add**, and fill in its credentials so Ellaworks can deploy agents on your behalf:

| Provider                         | Credentials                                                                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Vapi, Retell, ElevenLabs, Telnyx | API key (see [Vapi](/providers/vapi) and [ElevenLabs](/providers/elevenlabs))                                                   |
| AWS Bedrock Agents               | AWS Access Key ID, AWS Secret Access Key, AWS Region, and an optional Session Token (see [AWS Bedrock](/providers/aws-bedrock)) |

Credentials are never stored inline: pick an existing secret or create a new one in place. The environment stores a reference such as `${VAPI_API_KEY}`, and the encrypted value lives on the **Secrets** page (under **Delivery**), where you can rotate it without editing each environment.

Providers configured on the Global environment apply to every environment automatically — add the same provider to an individual environment only to override its credentials there.

![Configure a provider in the environment](/_fern-img/073473b11dc4c2dbfedb0d053644ce8caf787b39f368a6e5337d444e9cd1a765.webp)

#### Add variables

Under **Variables**, click **Add Variable** to define key-value pairs that get injected into your prompts at deployment time. Names may contain letters, numbers, dashes, and underscores. For example:

| Key                | Value                                                |
| ------------------ | ---------------------------------------------------- |
| `COMPANY_NAME`     | Acme Corp                                            |
| `SUPPORT_URL`      | [https://support.acme.com](https://support.acme.com) |
| `ESCALATION_PHONE` | +1-555-0100                                          |

Reference a variable in a prompt as `{{env.variables.COMPANY_NAME}}`. Ellaworks substitutes the values when it compiles the prompt for a deployment, so your prompt templates stay generic while each environment fills in the right values. Variables inherited from the Global environment are labeled **Inherited from Global**; setting the same key here overrides it.

![Add environment variables](/_fern-img/aeb4ad230499ebcf751a89f817ea743fb34c2685f649055298fb420aa84af30e.webp)

#### Save

Optionally configure an approval gate and drift detection (see below), then click **Save**.

> **Tip**
>
> When the same variable is set at several levels, the most specific value wins: **Agent** overrides **Fleet**, which overrides the **Environment**, which overrides **Global**.

### Approval gates

Turn on **Approval Gate** for an environment and choose **Required approvers** from your organization's members. Deployments to that environment are then held as pending approval, and run only after every required approver has approved. Approval gates are available on every environment except Global.

### Drift detection

Turn on **Drift Detection** to have Ellaworks check daily that agents deployed to that environment still match their expected configuration on the provider. Only one environment per organization can have drift detection enabled — typically `production`.

> **Note**
>
> Your plan may limit how many environments you can create. The create form shows your current usage and offers an upgrade when you've reached the limit.

### Why use environments?

* **Safe testing** — validate changes in `development` before they reach `production`
* **Separate credentials** — each environment can use its own provider API keys, stored as encrypted secrets
* **Variable substitution** — the same prompt template produces different output per environment (e.g. different support URLs, company names, or escalation contacts)
* **Approval gates** — optionally require named approvers to sign off before deploying to sensitive environments

## Create a Fleet (Optional)

Fleets are logical groupings of agents. If you only have a few agents, you can skip this step and come back later.

#### Navigate to Fleets

Click **Fleets** in the sidebar, then click **New Fleet**.

![Create a new fleet](/_fern-img/277d43008a9142288214eeb183ed95d12188ef660ac2eb780d3f9615abe03649.webp)

#### Configure the fleet

Enter a **Fleet Name**, an optional **Description**, and optionally assign agents, then click **Create Fleet**. Open the fleet afterwards to add or remove agents and define **Fleet Variables**. An agent can belong to only one fleet.

![Configure fleet details](/_fern-img/736edb1e4227d06462be6527b60086157e7578a280611d47816f71cc8da57f8e.webp)

### Why use fleets?

* **Shared variables** — fleet variables apply to every agent in the fleet, overriding environment values (agents can still override them)
* **Organization** — group agents by function (e.g. "Customer Support", "Sales Outbound", "Internal Tools") and see each deployment's fleet in deployment details

## Set up an LLM Provider (Optional)

LLM providers give Ellaworks access to language models for the playground and for governance policy evaluations. This is separate from the deployment provider credentials you set in an environment.

#### Navigate to LLM Providers

In the sidebar, open **Organization settings → LLM Providers** (organization owners and admins only).

![Navigate to LLM Providers settings](/_fern-img/deff980f8acad51163cffb3de4f1e8dc6a28d0c6aeefb0319b97a9ce265db4eb.webp)

#### Add a provider

Click **Add Provider**, choose a **Provider Type** (OpenAI, Anthropic, Google, or OpenRouter), give it a **Name**, and enter your **API Key**. Optionally set a **Base URL Override** or mark it as the **Default Provider** for that type.

![Add an LLM provider](/_fern-img/37d227c5a62d0c880c25cef889f14f13393c355074b22d252cf37bbdc8749be4.webp)

#### Test connectivity

After saving, click **Test Connection** to verify the API key works. Verified providers are marked **Verified** in the list.

![Test provider connectivity](/_fern-img/1c38b2c03565c0b548bc301365c668dc718bd133b4c4732f0d2869e4ffc8eebc.webp)

### Why set up an LLM provider?

* **Playground** — test prompts interactively against real models before deploying
* **Governance** — the default provider is also used for automated governance policy evaluations
* **Encrypted storage** — API keys are encrypted at rest, not stored in plaintext
* **Shared access** — team members can use the playground without needing their own API keys

## Next steps

#### [Using the Prompt Registry](/using-the-prompt-registry)

Author, version, and pull prompts at runtime

#### [Deploying Agents](/deploying-agents)

Deploy a voice agent with tools to Vapi

#### [API Reference](/api-reference)

Explore the full API