Environment Setup

This guide walks you through setting up the core building blocks of Ellaworx: 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.

Public vs Private Registries

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:

curl "https://platform.ellaworx.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):

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

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

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.

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.

When an integration such as Ellavox names the person who requested a deployment, that person cannot approve it, even if they are a required approver. They are not asked to: the deployment waits only for the other required approvers. If the requester is the environment’s only required approver, the deployment is refused, so add a second approver to environments that are deployed this way. Deployments started from Ellaworx itself do not record a separate requester and are not affected.

Drift detection

Turn on Drift Detection to have Ellaworx 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.

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.

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 Ellaworx 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.

Custom endpoints (OpenAI-compatible)

Choose OpenAI-Compatible (Custom Endpoint) for any model host that implements the OpenAI Chat Completions API, such as Oumi or a self-hosted vLLM server. Ellaworx calls {Base URL}/chat/completions. The endpoint must accept OpenAI’s request and streaming response format; the OpenAI Responses API is not used.

Example (Oumi): Base URL https://inference.oumi.ai/v1, your Oumi API key, model ID projects/EVYSUEX5ZT-1/deployments/1, and X-API-Key under Also send API key in header. If the deployment rejects max_tokens or temperature (“Only the default (1) value is supported”), turn on Reasoning model. For team agents, also set Reasoning effort to None: Oumi’s gpt-5 deployments reject tool calls on chat completions at their default effort (“Function tools with reasoning_effort are not supported … set reasoning_effort to ‘none’”). This matches Oumi’s own OpenAI SDK setup:

const client = new OpenAI({
  apiKey: process.env.OUMI_API_KEY,
  baseURL: "https://inference.oumi.ai/v1",
  defaultHeaders: { "X-API-Key": process.env.OUMI_API_KEY ?? "" },
});

Private and self-hosted endpoints. Requests to a custom endpoint carry your API key, so the host must resolve to a public internet address. Loopback, private (RFC 1918), link-local (including the cloud metadata address 169.254.169.254), carrier-grade NAT and IPv6 private ranges are refused, as are localhost, *.local and *.internal names. The check runs when the provider is saved and again on every connection, so a DNS change after saving can’t redirect requests to an internal address. To use a model server on a private network or on localhost (for example vLLM or Ollama during development), set ALLOW_PRIVATE_LLM_ENDPOINTS=true on the Ellaworx server.

Test Connection checks GET /models first. If the endpoint doesn’t implement it, Ellaworx sends a one-token chat completion to the first model ID instead. A failed test reports only the HTTP status (or that the address isn’t allowed), never the endpoint’s response body.

Custom endpoints are used for chat, playground, governance, and team agents. They aren’t used for embeddings, so team memory search falls back to recency for teams on a custom endpoint. The provider type can’t be changed after creation; create a new provider instead.

A team on a custom endpoint runs every member on the team model. Per-member model and provider overrides are turned off in the member editor and refused by the API, and the team model must be one of the endpoint’s configured model IDs.

Changing a team’s LLM provider

An org admin can switch a team’s provider and model under Team → Settings → General. Saving a new provider asks for confirmation, then:

• clears every member’s model and provider override, so the whole team runs on the new provider and the team model;
• picks a model the new provider serves when none is chosen (a custom endpoint’s first configured model);
• leaves semantic memory search on only for OpenAI providers; other providers fall back to recent memories.

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