# Environments

Keep development, staging, and production matchmaking separate.

Source: https://birdhouse.tech/docs/environments/

Every new ticket has a canonical environment. Tickets from different environments never match, even when they have identical metadata, no constraints, or fully relaxed timeout rules.

## Configure the client

Set the environment once when creating a Roblox client:

```luau
local client = MatchmakingClient.new({
    baseUrl = "https://matchmaking.example.com",
    environment = "staging",
})
```

The SDK copies this setting and puts it in every create action's `options.environment`. A session cannot override it. Use a separate client for a different environment.

## Environment names

Keys contain 1–32 lowercase ASCII letters, digits, underscores, or hyphens and must begin with a letter. Examples include `dev`, `staging`, `prod`, and `playtest-2`.

The SDK validates the format. The service separately validates its configured allowlist. The service's default list is `dev`, `staging`, and `prod`; a deployment can configure 1–20 distinct keys through `MATCHMAKING_ENVIRONMENTS`.

An environment with a valid name can still be rejected when that deployment does not allow it.

## Direct HTTP requests

The environment belongs at the top level of create options:

```json
{
  "actions": [
    {
      "type": "create",
      "options": {
        "environment": "dev",
        "players": [{ "id": "123456789" }],
        "meta": { "mode": "duel" },
        "constraints": { "type": "playerCount", "min": 2, "max": 2 }
      }
    }
  ]
}
```

`meta.environment` is ordinary metadata and cannot select or override the canonical environment. Confirm and cancel actions continue to use the ticket ID without an environment argument.

## Isolation and grouping

Environment isolation is an unconditional service boundary. Mode, region, role, and other metadata need their own [matching rules](https://birdhouse.tech/docs/constraints/) when they must restrict a match.

An environment is not an authentication credential or an authorization boundary. Access-token authentication is unavailable in this phase; configure access to your deployment separately.

## Existing tickets and upgrades

Legacy tickets without an environment remain in a reserved `_unlabeled` group. They are not assigned to `prod`. The SDK accepts missing environments and `_unlabeled` in legacy responses, but neither is a valid client setting for creating new tickets.

The environment-aware API service, workers, monitoring, and SDK callers require a coordinated rollout. All old workers must stop before relying on isolation. Keep legacy ticket and match records available for their original retry window. See [release notes and migration](https://birdhouse.tech/docs/releases/).