> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Environments
> Isolate production, staging, and development resources within a workspace.
An environment is an isolated context within a workspace. Each environment has its own agents, instances, sandboxes, and credentials, keeping production and development cleanly separated.
## How it works
Within a workspace, you create environments such as `production`, `staging`, and `development`. Resources are scoped to the active environment, determined by the credential you use. There is no need to pass the environment in requests; it is derived from your API key or OAuth client.
```
Workspace
├── production → its own resources & credentials
├── staging → its own resources & credentials
└── development → its own resources & credentials
```
## What is isolated per environment
Each environment gets its own independent copy of runtime resources. The fleet and agent registry are shared at the workspace level — only the running infrastructure is separated.
| Resource | Per environment? | Notes |
| ------------------------------------- | ---------------- | -------------------------------------------------- |
| Agent instances | ✓ | Same agent image, separate running instances. |
| Sandboxes | ✓ | Separate execution contexts with independent TTLs. |
| Datasources & knowledge stores | ✓ | Production data is never visible to development. |
| Credentials (API keys, OAuth clients) | ✓ | Each credential targets exactly one environment. |
| Fleet definitions | ✗ | Shared across environments within a workspace. |
| Agent registry entries | ✗ | Shared; you register once, deploy per environment. |
Hexel's multi-region routing uses the environment to co-locate resources. When you create a `production` environment in a workspace associated with a region, instances, sandboxes, and data stores are provisioned in that region. This ensures data residency without additional configuration.
## Getting started
Create environments in the Console under **IAM → Environments**. For each environment, create a dedicated API key or OAuth client — the credential determines which environment your requests target.
```
Console → IAM → Environments → Create environment → Name it "production"
Console → IAM → Service Users → Create API key (select "production" environment)
```
When submitting orchestration tasks, you pass the `environment_id` explicitly:
```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/orchestrator/v1/tasks \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fleet_id": "YOUR_FLEET_ID",
"environment_id": "YOUR_ENVIRONMENT_ID",
"workspace_id": "YOUR_WORKSPACE_ID",
"input": "Process today'\''s support tickets"
}'
```
Find your `environment_id` in the Console under **IAM → Environments**.
## Common mistakes
* **Sharing one credential across environments.** This breaks isolation; use a separate credential per environment.
* **Testing in production.** Use a development environment for experimentation.
## Best practices
* Maintain at least `production` and `development` environments.
* Issue separate credentials per environment.
* Mirror configuration across environments to make promotion predictable.
## Related pages
The full scoping model.
Per-environment credentials.
Production credentials.
How environment scoping is applied.