Environments

Tag each execution with the end-customer it serves, so cost, quota, and analytics split cleanly per customer

When one agent serves multiple end-customers, you need to know which run belongs to which customer. Environments are the tag you attach to every execution to make that split work — for cost reporting, quota enforcement, and per-customer analytics.

An environment is not a deployment stage (dev/staging/prod). For staging vs. production runs, use the execution mode and separate agents. Environments are about who the run is for, not which build served it.

When to use environments

Use environments when your backend embeds Fruxon to serve multiple customers from the same agent. Typical setups:

B2B SaaS — one agent per product feature; you want to know what Acme Corp's usage costs separately from Globex's.
Reseller / agency — you sell agent-powered automation to many end-clients off one Fruxon org.
Multi-tenant chat product — each conversation belongs to one of your tenants.

If your agent serves one audience (your own users), you don't need environments — leave the field unset.

How environments work

An environment is a tenant-scoped row identified by a slug. Pass the slug on every relevant execution and Fruxon:

Auto-creates the environment on first sighting (no upfront setup required).
Tags the execution record with the slug.
Splits cost and quota analytics by environment in the dashboard and the per-environment summary endpoint.

Slug rules

A slug is a short, URL-safe identifier:

Must start with a lowercase letter.
Allowed characters: lowercase letters, digits, underscores. No hyphens.
Maximum 64 characters.

Pattern: ^[a-z][a-z0-9_]+$

Examples: acme_corp, globex, customer_123.

The one-slug-per-customer rule

One slug per end-customer, reused across every execution for that customer.

This is the single most important thing to get right. The slug should map to a stable entity in your product — a tenant id, account id, workspace id — translated into a slug-safe form. Same customer → same slug, every time.

Anti-pattern

Don't send a UUID per request, a session id, or a timestamp. Each unique slug auto-creates a row, and you'll hit the per-organization cap of 1000 environments quickly. If you see request ids in your slugs, that's the bug.

Passing a slug

From the API

Send environmentSlug in the body of any :execute or :stream call:

curl -X POST "https://api.fruxon.com/v1/tenants/$TENANT/agents/$AGENT:execute" \
  -H "X-API-KEY: $FRUXON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": { "user_query": "Refund my last order" },
    "sessionId": "conv-7f2a",
    "environmentSlug": "acme_corp"
  }'

Revision-pinned execute (/agents/{agent}/revisions/{revision}:execute) accepts the same field.

From connectors

When you bind a connector (Slack, Telegram, webhook, …) to an agent, you can pin it to an environment. Every message that arrives through that connector is tagged with the connector's environment automatically — no API change in your channel handler.

From the SDK

from fruxon import FruxonClient

client = FruxonClient(api_key=os.environ["FRUXON_KEY"], tenant="my-org")
client.execute(
    agent="support-bot",
    parameters={"user_query": "Where's my order?"},
    environment_slug="acme_corp",
)

What you get back

The execution record carries the slug, which surfaces in:

The Executions list in monitoring — filter by environment to see only one customer's runs.
The per-environment summary endpoint — execution count, total cost, last activity per environment, for one agent.
Budget alerts — track cost separately per environment.

Limits

Limit	Default	What happens at the limit
Environments per organization	1000	New auto-create requests fail with `400 Bad Request`; existing environments continue to work
Slug length	64 chars	Request rejected with `400` before the call reaches the agent
Slug format	`^[a-z][a-z0-9_]+$`	Request rejected with `400`

When the cap is reached

Your organization admins receive an email with diagnostics — recently-created slugs, count created in the last 24h, and a likely-cause hint. If the cap was hit by a misconfigured integration (UUIDs as slugs, for example), you'll usually see the bug in the sample slugs.

A soft-warn email also fires when the organization crosses 80% of the cap, so you have time to fix a leaking integration before runs start failing.

To raise the cap, delete unused environments via the Settings → Environments page, or contact support.

Managing environments

Settings → Environments lists every environment in your organization with execution count and last-used timestamp. You can:

Delete unused environments (the execution records keep their slug; only the registry row is removed).
Rename the display name (the slug itself is immutable — it's the identifier).
Create an environment explicitly via API or UI before any execution lands, if you want to pre-register the display name.

FAQ

What happens if I send a slug I've never used before? The environment is auto-created on first use. No setup call required.

Is the slug visible to the end-customer? No. It's a server-side tag. End-customers never see it.

Can I change a slug after the fact? No. Slugs are identifiers — change them and the execution history splits. If you renamed a customer in your system, register the new slug going forward and either keep or delete the old one.

Do I have to set this for every execution? No, it's optional. Leave it unset for runs not tied to a specific end-customer. Just be consistent — don't tag some of a customer's runs and leave others untagged, or the analytics will look incomplete.

Does this affect data isolation between my customers? No. Environments are an analytics dimension, not a security boundary. Fruxon's tenant isolation operates at the organization level — your data is isolated from other Fruxon customers, but everything within your org is in one tenant. Don't rely on environments to separate sensitive data.

Environments

On this page