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

# prepare-environment

Prepare a container environment for a task, checking for existing images first.

## Description

The `prepare-environment` prompt implements the recommended CHECK-PREPARE-EXECUTE workflow:

1. **CHECK** - Search for existing prepared environments
2. **PREPARE** - Import and configure if not found
3. **EXECUTE** - Run the task with the prepared environment

This ensures maximum reuse of prepared images and follows Contree best practices.

## Parameters

| Parameter  | Type   | Required | Default            | Description                                         |
| ---------- | ------ | -------- | ------------------ | --------------------------------------------------- |
| `task`     | string | Yes      | -                  | Description of the task to perform                  |
| `base`     | string | No       | `python:3.11-slim` | Base image to use                                   |
| `project`  | string | No       | `None`             | Project name for scoping (uses `common` if not set) |
| `packages` | string | No       | `None`             | Packages to install (space-separated)               |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "task": "Train ML model",
  "base": "python:3.11-slim",
  "packages": "numpy pandas scikit-learn"
}
```

Returns instructions like:

````markdown theme={null}
Prepare an environment for: Train ML model

**Step 1: CHECK for Existing Environment**

Search for prepared environments:
```json
// list_images
{"tag_prefix": "common/"}
````

If a suitable environment exists (has required packages), skip to Step 3.

**Step 2: PREPARE Environment (if not found)**

2a. Import base image:

```json theme={null}
// import_image
{"registry_url": "docker://docker.io/python:3.11-slim"}
```

2b. Install dependencies with `disposable=false`:

```json theme={null}
// run
{
  "command": "pip install numpy pandas scikit-learn",
  "image": "<result_image>",
  "disposable": false
}
```

2c. Tag for reuse:

```json theme={null}
// set_tag
{"image_uuid": "<result_image>", "tag": "common/numpy-env/python:3.11-slim"}
```

**Step 3: EXECUTE Task**

Use the prepared environment:

```json theme={null}
// run
{"command": "<task command>", "image": "tag:common/numpy-env/python:3.11-slim"}
```

```

## Tag Generation

The prompt automatically generates a tag following the convention:
```

\{scope}/\{purpose}/\{base}:\{tag}

````

- **scope**: Uses `project` parameter if provided, otherwise `common`
- **purpose**: Derived from first package name (e.g., `numpy-env`) or `custom-env`
- **base:tag**: From `base` parameter

## Example Usage

### ML Development Environment

```json
{
  "prompt": "prepare-environment",
  "args": {
    "task": "Run data analysis notebook",
    "packages": "jupyter pandas matplotlib seaborn"
  }
}
````

### Project-Specific Environment

```json theme={null}
{
  "prompt": "prepare-environment",
  "args": {
    "task": "Run API tests",
    "project": "myproject",
    "packages": "pytest requests httpx"
  }
}
```

Generates tag: `myproject/pytest-env/python:3.11-slim`

### Custom Base Image

```json theme={null}
{
  "prompt": "prepare-environment",
  "args": {
    "task": "Compile Rust project",
    "base": "rust:1.75-slim"
  }
}
```

## See Also

* [install-packages](./install-packages) - Simpler package installation
* [build-project](./build-project) - Full build workflow
* [Tagging Convention](../resources) - Tag naming guide