> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> /v1/environments — reusable sandbox runtime, template, and dependency definitions

An environment is a named sandbox template. Multiple agents and sessions can reference the same one; edit it once and every referencing session picks it up on its next run.

<Note>
  Creating an environment provisions nothing. The sandbox is created when a session referencing it runs for the first time.
</Note>

## Create an environment

```
POST https://api.profy.cn/v1/environments
```

<ParamField body="name" type="string" required>
  Environment name.
</ParamField>

<ParamField body="template" type="object">
  Sandbox template.
</ParamField>

<Expandable title="template fields">
  <ParamField body="runtime" type="string" default="python">
    One of `python`, `node`, `browser`, `custom`.
  </ParamField>

  <ParamField body="templateId" type="string">
    Base image alias. Falls back to the platform default.
  </ParamField>

  <ParamField body="dependencies" type="string[]">
    Packages installed after provisioning, max 50. `python` uses `pip`, `node` uses `npm`.
  </ParamField>

  <ParamField body="capabilities" type="string[]">
    Capability declarations.
  </ParamField>

  <ParamField body="resource_limits" type="object">
    `cpu` / `memory` / `timeout_seconds`.
  </ParamField>
</Expandable>

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/environments \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customs processing",
    "template": {
      "runtime": "python",
      "dependencies": ["pandas", "openpyxl"],
      "resource_limits": { "timeout_seconds": 600 }
    }
  }'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "id": "env_abc",
    "name": "Customs processing",
    "template": { "runtime": "python", "dependencies": ["pandas", "openpyxl"] },
    "created_at": "...",
    "updated_at": "..."
  }
}
```

## Bind it to a session

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/sessions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "my-expert", "environment_id": "env_abc"}'
```

The environment is resolved before each run, and a session's environment wins over the agent's own sandbox config. You can iterate on dependencies without recreating the session.

## Other operations

| Method   | Path                      | Notes                                         |
| -------- | ------------------------- | --------------------------------------------- |
| `GET`    | `/v1/environments?limit=` | List your environments, max 100               |
| `GET`    | `/v1/environments/{id}`   | Detail                                        |
| `PATCH`  | `/v1/environments/{id}`   | Rename or update the template                 |
| `DELETE` | `/v1/environments/{id}`   | Soft delete; running sandboxes are unaffected |

## Errors

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| `400`  | Missing `name`, or invalid `template` (runtime value, dependency count, …) |
| `401`  | Authentication failed                                                      |
| `404`  | Environment not found or not yours                                         |

## Next steps

<CardGroup cols={2}>
  <Card title="Sessions" icon="comments" href="/en/developers/api/sessions">
    Create long-lived sessions and append events
  </Card>

  <Card title="Manage Agents" icon="robot" href="/en/developers/api/agents">
    Create and publish Experts via API
  </Card>
</CardGroup>