# Best Practices
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/best-practice



## Common strategy on setting up deployment

* **GPU type + GPU count** = performance per replica
* **Replicas** = traffic capacity and availability

Start with the smallest setup that reliably meets baseline needs, then scale deliberately based on real traffic and observability:

<Steps>
  <Step title="1 replica set up: Choose a GPU type and gpu_count that meets single-replica performance goals" />

  <Step title="Autoscaling set up: Use replicas to absorb traffic spikes and concurrency" />
</Steps>

***

## Choosing performance setup: GPU types & GPUs per replica

Choosing the right dedicated endpoint configuration depends on your workload’s priorities: latency, throughput, model size, and cost efficiency.

### GPU type

GPU type determines the performance profile of each replica, including memory capacity, throughput, and cost.

In general:

| Higher-end GPUs                                                                                                                                                              | Mid-range GPUs                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Largest models</li><li>High throughput production workloads</li><li>Low latency requirements</li><li>Long context windows</li><li>Heavy concurrent traffic</li></ul> | <ul><li>Smaller or optimized models</li><li>Internal tools</li><li>Moderate traffic</li><li>Cost-sensitive deployments</li><li>Testing before scaling</li></ul> |

<Tip>
  **Rule of thumb:** Choose the smallest GPU type that supports your model and region. If performance is insufficient, first scale GPU type or GPUs per replica before aggressively increasing replicas.
</Tip>

### GPUs per replica (`gpu_count`)

`gpu_count` defines how many GPUs power a single replica.

This primarily affects:

* Per-request latency
* Maximum throughput per replica
* Ability to serve larger or more demanding workloads

| Lower GPU count per replica                                                                                                       | Higher GPU count per replica                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Lower baseline cost</li><li>Smaller workloads</li><li>Simpler traffic patterns</li><li>Experimental deployments</li></ul> | <ul><li>Higher throughput per replica</li><li>Lower latency for large workloads</li><li>Bigger model serving requirements</li><li>Better vertical scaling before horizontal expansion</li></ul> |

<Tip>
  **Rule of thumb:** Start small when you are testing traffic, usage is uncertain, internal deployment, cost control matters. Scale up when requests are latency-sensitive, individual replicas saturate, you need stronger single-endpoint performance

  Avoid Over-relying on replicas to solve underpowered replicas. More replicas help concurrency, but they do not fix poor per-request latency caused by insufficient GPU resources.
</Tip>

***

## Choosing number of replicas

Replicas determine how much baseline and burst traffic your deployment can handle.

### Min replicas: guaranteed baseline capacity

Minimum replicas are always allocated while the endpoint is active.

Use higher `min_replicas` when:

* You need predictable low latency
* Traffic is steady
* Cold starts are unacceptable
* Capacity predictability matters

Use lower `min_replicas` when:

* Traffic is irregular
* You optimize for cost
* Batch or internal workloads
* Occasional warm-up is acceptable

### Max replicas: burst scaling ceiling

Maximum replicas define how far autoscaling can expand if capacity is available.

Use higher `max_replicas` when:

* Traffic spikes significantly
* Usage is unpredictable
* You need burst headroom

Use lower `max_replicas` when:

* Workload is stable
* Budget control matters
* Capacity is predictable

<Tip>
  **Rule of thumb:**

  * min\_replicas - what you always need
  * max\_replicas - what you may need during peaks
</Tip>

<Note>
  **Note that:**

  * Min replicas are guaranteed while active. If you stop the endpoint the reservation will be freed up.
  * Max replicas scaling depends on available capacity and may not always be continuously available after scale-down. [Read more in Capacity section](/ai-models-inference/dedicated-endpoints/capacity-and-scaling)
</Note>


# Billing Policy
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/billing-policy



### Billing while active

* A dedicated endpoint is considered **active, accessible, and billable** when **at least one replica is running**
* When **one or more replicas are running**, the endpoint is available to serve traffic and billing charges apply.
* When **zero replicas are running**, the endpoint is not accessible and billing charges do not apply.
* Charges may vary depending on your custom contract or work order.

### Autoscaling costs

Scaling above or below minimum replicas adjusts billing dynamically on a PAYG basis.

### Capacity retention

As long as your endpoint remains active, minimum replicas remain allocated to you. Once capacity is released, it may be reassigned and may not be immediately available again.

### Specific cases

| Lifecycle step                                         | Billing     |
| ------------------------------------------------------ | ----------- |
| Capacity provisioning, `not ready` , `partially ready` | Not billed  |
| Capacity provisioned to the endpoint,`ready` status    | Billed      |
| Replica restarts                                       | Not billied |
| Graceful shutdown for rolling update, endpoint stop    | Not billed  |


# Capacity, availability, and service guarantees
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/capacity-and-scaling



### Capacity availability

Dedicated endpoint deployment depends on available capacity across different regions. Not all listed GPU types may be available at all times. Availability depends on current regional capacity.

### Capacity after stops, incidents, and maintenance

Self-service dedicated endpoints are provisioned on Nebius AI Cloud on-demand (pay-as-you-go) capacity. This capacity is drawn from a shared pool and is allocated to your endpoint only while it is active — **it is not a long-term reservation, and the minimum replicas guarantee applies only while the endpoint is running.**

**When an endpoint stops, its GPU capacity is released back to the shared pool. This applies regardless of why the endpoint stopped**:

* You stop the endpoint manually
* The endpoint is interrupted by an incident
* The endpoint is stopped for scheduled or emergency maintenance

When the endpoint starts again, capacity is requested from the pool anew and allocated based on availability at that moment. There is no mechanism that holds your previous GPUs for the endpoint or returns them after an interruption. As a result:

* After a restart, the endpoint may stay in **Starting / Not ready**, or reach only **Partially ready**, until sufficient capacity becomes available. See [Lifecycle & Readiness Status](/ai-models-inference/dedicated-endpoints/lifecycle-and-status).
* During periods of high demand, or for scarce GPU types, restarting may take significantly longer than the initial deployment, and capacity may be temporarily unavailable.

This is the standard behavior of on-demand capacity in Nebius AI Cloud, on which self-service dedicated endpoints run: without a reservation, GPU resources are taken from a shared pool and returned to it when they stop — whether stopped by you or by a maintenance event — and recovery after maintenance or an incident does not restore the capacity your endpoint used before. For details on how on-demand and reserved capacity work, see [Capacity reservations for Compute virtual machines](https://docs.nebius.com/compute/virtual-machines/reservations) in the Nebius AI Cloud documentation.

<Note>
  If your workload requires guaranteed capacity across restarts, incidents, and maintenance windows, [contact our Sales team to reserve dedicated GPU capacity](https://nebius.com/services/token-factory/enterprise-grade-inference#token-factory-enterprise-sales-form)
</Note>

### Minimum replicas guarantee

Minimum replicas are reserved and non-preemptible and remain allocated to your deployment for as long as the endpoint is active. If the endpoint stops for any reason, this allocation is released — see the section above.

### Maximum replicas scaling

Scaling above minimum replicas depends on available burst capacity and is not guaranteed indefinitely. Additional replicas may be reclaimed after scale-down and may not always be available again without sufficient capacity.

### SLA

Self-service dedicated endpoints do not include a formal SLA unless covered by contract. Historical average monthly request success rate has been approximately 99.9%.

<Note>
  If you encounter capacity errors or are unable to scale beyond the minimum number of replicas, [contact our Sales team to reserve dedicated GPU capacity](https://nebius.com/services/token-factory/enterprise-grade-inference?_gl=1*b0acui*_gcl_au*MTAwNTQwNDk0NC4xNzcwMjkyMzc3LjExODU3MTgzMTAuMTc3NjA5NDQ4Ni4xNzc2MDk0NDg1#token-factory-enterprise-sales-form)
</Note>


# Control & Data Plane
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/control-data-plane



## Terminology

| **Term**          | **Description**                                                                                                                |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **Template**      | A deployable performance “blueprint” for a model. Templates define which `flavor_name`, `gpu_type`, and regions are supported. |
| **Flavor**        | A template's sub-option (e.g. `base`, `fast`) with different performance/throughput/costs characteristics.                     |
| **Endpoint**      | Dedicated deployment with API access                                                                                           |
| **endpoint\_id**  | Identifier used for update/delete operations.                                                                                  |
| **routing\_key**  | The model identifier you pass to inference calls. Returned when you create an endpoint.                                        |
| **Control plane** | Sets up the configuration and settings of your endpoints. Has common base URL API.                                             |
| **Data plane**    | Processes model inference requests. Has regional base URL API.                                                                 |

## Control plane

Dedicated Endpoints Control Plane is a managedment layer for all configurations operations:

* Creating & updating endpoints
* Uploading models / weights
* Scaling configs (min/max replicas)
* Monitoring setup

Use common base URL API for all dedicated endpoint management operations:

```text theme={null}
https://api.tokenfactory.nebius.com
```

## Data plane

Dedicated Ednpoints Data Plane processes model inference requests. It has regional base URL API. Region impacts latency, data locality, and regulatory compliance.

Use a region-appropriate base URL for your inference calls:

| Endpoint region | Inference base URL                                |
| :-------------- | :------------------------------------------------ |
| `eu-north1`     | `https://api.tokenfactory.nebius.com`             |
| `eu-west1`      | `https://api.tokenfactory.eu-west1.nebius.com`    |
| `us-central1`   | `https://api.tokenfactory.us-central1.nebius.com` |

<Note>
  Using the respective inference base URL avoids unnecessary global routing and reduces round-trip latency.
</Note>

## Endpoint Observability

<Card title="Observability" icon="chart-line" href="https://docs.tokenfactory.nebius.com/ai-models-inference/observability">
  Check out Observability Documentation section here
</Card>


# Custom model weights
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/custom-weights



**Working with custom model weights** is currently in beta and available on request. If you’d like to deploy or work with custom fine-tuned model weights, [please contact our Support team to enable access](https://tokenfactory.nebius.com/?modals=contact-us) and guide you through the current setup process. Availability, supported configurations, and onboarding steps may vary during the beta period.


# Quickstart: Deploy via API
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/deploy-api



## Overview

Deploying a dedicated endpoint via API takes three steps:

1. List available model templates
2. Create a dedicated endpoint
3. Send inference requests

For updating, listing, and deleting endpoints, see **Operating dedicated endpoints**.

## List model templates

List model templates that can be used to create a dedicated endpoint.

```http theme={null}
GET /v0/dedicated_endpoints/templates
```

<CodeGroup>
  ```python Python theme={null}
  import os, json, requests

  CONTROL_PLANE_BASE_URL = "https://api.tokenfactory.nebius.com"
  API_TOKEN = os.environ["API_TOKEN"]

  r = requests.get(
      f"{CONTROL_PLANE_BASE_URL}/v0/dedicated_endpoints/templates",
      headers={"Authorization": f"Bearer {API_TOKEN}"},
  )
  r.raise_for_status()
  print(json.dumps(r.json(), indent=2))
  ```

  ```shellscript cURL theme={null}
  curl -sS \
    -H "Authorization: Bearer $API_TOKEN" \
    "https://api.tokenfactory.nebius.com/v0/dedicated_endpoints/templates"
  ```
</CodeGroup>

<Tip>
  Use the template response as the source of truth for valid combinations of `model_name`, `flavor_name`, `gpu_type`, `gpu_count` and `region`.
</Tip>

## Create dedicated endpoint

Create a dedicated endpoint from one of the available model templates.

```http theme={null}
POST /v0/dedicated_endpoints
```

<CodeGroup>
  ```python Python theme={null}
  import os, json, requests

  CONTROL_PLANE_BASE_URL = "https://api.tokenfactory.nebius.com"
  API_TOKEN = os.environ["API_TOKEN"]

  payload = {
      "name": "GPT-20B Endpoint",
      "description": "Dedicated GPT-20B for internal apps",
      "model_name": "openai/gpt-oss-20b",
      "flavor_name": "base",
      "gpu_type": "gpu-h100-sxm",
      "gpu_count": 1,
      "region": "eu-north1",
      "scaling": {"min_replicas": 1, "max_replicas": 2},
  }

  r = requests.post(
      f"{CONTROL_PLANE_BASE_URL}/v0/dedicated_endpoints",
      headers={"Authorization": f"Bearer {API_TOKEN}"},
      json=payload,
  )
  r.raise_for_status()
  print(json.dumps(r.json(), indent=2))
  ```

  ```shellscript cURL theme={null}
  curl -sS -X POST \
    "https://api.tokenfactory.nebius.com/v0/dedicated_endpoints" \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "GPT-20B Endpoint",
      "description": "Dedicated GPT-20B for internal apps",
      "model_name": "openai/gpt-oss-20b",
      "flavor_name": "base",
      "gpu_type": "gpu-h100-sxm",
      "gpu_count": 1,
      "region": "eu-north1",
      "scaling": { "min_replicas": 1, "max_replicas": 2 }
    }'
  ```
</CodeGroup>

The response includes endpoint metadata, including:

* `endpoint_id`
* `routing_key`

Use `endpoint_id` to manage the endpoint through the control plane. Use `routing_key` as the model identifier when sending inference requests to the data plane.

<Note>
  Initial deployment can take several minutes. While provisioning, inference may fail (often `404`) until the endpoint is routable.
</Note>

## Send inference requests

Once the endpoint is ready, send requests to the OpenAI-compatible data plane under `/v1`.

Use the `routing_key` returned by the control plane as the `model` value in inference requests:

```text theme={null}
model = "<routing_key>"
```

Use a region-appropriate base URL for your inference calls. Example request URL:

```text theme={null}
https://api.tokenfactory.us-central1.nebius.com/v1/chat/completions
```

<CodeGroup>
  ```python Python (OpenAI SDK) theme={null}
  import os
  from openai import OpenAI

  API_TOKEN = os.environ["API_TOKEN"]

  # Choose based on the endpoint region
  INFERENCE_BASE_URL = "https://api.tokenfactory.us-central1.nebius.com/v1"

  client = OpenAI(
      base_url=INFERENCE_BASE_URL,
      api_key=API_TOKEN,
  )

  routing_key = "<routing_key>"  # use exactly what the API returned
  response = client.chat.completions.create(
      model=routing_key,
      messages=[{"role": "user", "content": "Explain the difference between LLM fine-tuning and RAG."}],
  )

  print(response.choices[0].message.content)
  ```

  ```shellscript cURL theme={null}
  curl -sS "https://api.tokenfactory.us-central1.nebius.com/v1/chat/completions" \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<routing_key>",
      "messages": [
        { "role": "user", "content": "Hello from my dedicated endpoint!" }
      ]
    }'
  ```
</CodeGroup>

<Note>
  We expose OpenAI-compatible inference routes under `/v1`. Template availability determines what kinds of models you can deploy (today, publicly available templates are primarily chat-capable).
</Note>


# Quickstart: Deploy in UI
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/deploy-ui

Dedicated endpoints can be deployed and managed through the Token Factory UI, with API workflows also available for automation.

You can create a dedicated endpoint from either of these UI locations:

* Explore page: [https://tokenfactory.nebius.com/](https://tokenfactory.nebius.com/)
* Inference → Model Endpoints: [https://tokenfactory.nebius.com/endpoints](https://tokenfactory.nebius.com/endpoints)

<Columns>
  <Column>
    <Frame>
      <img alt="Image" />
    </Frame>
  </Column>

  <Column>
    <Frame>
      <img alt="Image" />
    </Frame>
  </Column>
</Columns>

1. Explore page [https://tokenfactory.nebius.com/](https://tokenfactory.nebius.com/)
2. Inference/Model Endpoints [https://tokenfactory.nebius.com/endpoints](https://tokenfactory.nebius.com/endpoints)

From there, select a supported model template and complete the deployment configuration, including region, GPU configuration, and autoscaling settings.

<Columns>
  <Column>
    <Frame>
      <img alt="Image" />
    </Frame>
  </Column>

  <Column>
    <Frame>
      <img alt="Image" />
    </Frame>
  </Column>

  <Column>
    <Frame>
      <img alt="Image" />
    </Frame>
  </Column>
</Columns>

## Walkthrough on UI deployment

<iframe title="YouTube video player" />

<Note>
  **Prefere automation?**\
  For API-based deployment, see [Deploy in API ](/ai-models-inference/dedicated-endpoints/deploy-api)section
</Note>

## Using endpoint

Go to **Inference → Model Endpoints** and open your private endpoint card.

<Frame>
  <img alt="Image" />
</Frame>

There, you can view key deployment details, including:

* Endpoint ID
* Routing key
* Model
* GPUs per replica
* Minimum and maximum replicas
* Deployment status
* Ready-to-use code snippets

To update configuration, click **Edit Endpoint**.

<Columns>
  <Column>
    <Frame>
      <img alt="Image" />
    </Frame>
  </Column>

  <Column>
    <Frame>
      <img alt="Image" title="Image" />
    </Frame>
  </Column>
</Columns>

To check observability metrics you can either:

1. Open dedicated endpoints model card and click Observability button below
2. Go to observability section and set filters to your enpoint: [https://tokenfactory.nebius.com/observability](https://tokenfactory.nebius.com/observability?monitoring_model=all\&monitoring_cloud_account_id=all\&monitoring_region=all)

Read more at [Observability section](/ai-models-inference/observability)

## Walkthrough on Operating Dedicated Endpoints

See **Walkthrough on Operating Dedicated Endpoints** for deployment management, scaling, and operational best practices

<iframe title="YouTube video player" />


# FAQ & Troubleshooting
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/faq



## Troubleshooting common errors

|                     Status | Typical cause                                                      | Fix                                                                                                                |
| -------------------------: | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
|         `401 Unauthorized` | Missing/invalid token                                              | Ensure `Authorization: Bearer ...` is set and token is active                                                      |
|            `403 Forbidden` | Token lacks permission                                             | Use a token with dedicated endpoint permissions                                                                    |
|            `404 Not Found` | Endpoint not ready, wrong inference domain, or wrong `routing_key` | Wait for readiness; use correct inference base URL for the endpoint region; pass `routing_key` exactly as returned |
|             `409 Conflict` | Capacity or config conflict                                        | Choose a supported GPU/region combo from templates or reduce max replicas                                          |
| `422 Unprocessable Entity` | Invalid payload values                                             | Validate fields against templates (gpu types, flavors, regions, counts)                                            |

## I finetuned a model and want to deploy it via Dedicated endpoint

**Working with custom model weights** is currently in beta and available on request. If you’d like to deploy or work with custom fine-tuned model weights, [please contact our Support team to enable access](https://tokenfactory.nebius.com/?modals=contact-us) and guide you through the current setup process. Availability, supported configurations, and onboarding steps may vary during the beta period.

## Base model is not available in the list

We strive to support the most popular model balancing variety and performance excellence. If the model you're looking for is absent in the list - [please contact our Support team](https://tokenfactory.nebius.com/?modals=contact-us) mentioning:

* Exact model you're looking for with Hugging Face weights link
* Your project and traffic details

Our team will review your case and make a decision on model support

## Region is not available in the list

We support several datacenters worldwide and the deployment options depends on capacity available. Sometimes the region and GPU type combination you're looking for may not be available. Still you can [contact our Sales team](https://nebius.com/services/token-factory/enterprise-grade-inference?_gl=1*mezsjw*_gcl_au*MTAwNTQwNDk0NC4xNzcwMjkyMzc3Ljk4MTA4NzYzMy4xNzc3NTM3MTg5LjE3Nzc1MzgzMzM.#token-factory-enterprise-sales-form) to plan a capacity reserve in a specific region.

### Can I bring down my Dedicated Endpoint when I don't have traffic so I don't overpay?

Yes, use `enabled` parameter in request to enable/disable the endpoint. [Read more on this in Operations section.](/ai-models-inference/dedicated-endpoints/operating)\
Note that stopping the endpoint releases the capacity and you may not start it again if the capacity is taken by the other user and there are no free capacity at the moment.


# Lifecycle & Readiness Status
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/lifecycle-and-status



Dedicated Endpoints expose **two separate status types**:

1. **Lifecycle - What stage the deployment is in**
2. **Readiness - Whether the endpoint can currently serve traffic**

This distinction helps separate deployment progress from actual availability.

***

## Lifecycle Status

### Starting

Endpoint is being created or started.\
Provisioning is in progress, and traffic may not be available yet.

### Updating

Endpoint is applying configuration changes.\
Traffic may continue, but capacity can temporarily degrade.

### Running

Endpoint is deployed and expected to operate normally.

### Warning

A deployment issue requires attention.\
The endpoint may still serve traffic depending on readiness.

<Note>
  **If unresolved for more than 3 hours, contact support.**
</Note>

### Stopping

Stop was requested, but shutdown is still in progress.

### Stopped

Endpoint is intentionally disabled.

***

## Readiness Status

### Not ready

Endpoint cannot reliably serve requests.

**Expected during:** Starting, Stopping, or Stopped

### Partially ready

Endpoint can serve traffic, but below expected capacity.\
Some replicas are still starting, updating, or unavailable.

<Note>
  **If unresolved for more than 3 hours, contact support.**
</Note>

### Ready

Endpoint is fully provisioned and ready for expected traffic.

***

## Common Status Examples

| Lifecycle | Readiness       | Meaning                              |
| :-------- | :-------------- | :----------------------------------- |
| Starting  | Not ready       | Provisioning                         |
| Starting  | Partially ready | Serving, still scaling               |
| Updating  | Ready           | Serving normally during update       |
| Running   | Ready           | Fully operational                    |
| Running   | Partially ready | Degraded capacity                    |
| Running   | Not ready       | Unexpected outage                    |
| Error     | Ready           | Serving, but deployment issue exists |
| Error     | Not ready       | Deployment failure                   |
| Stopping  | Partially ready | Shutting down                        |
| Stopped   | Not ready       | Fully stopped                        |

<Note>
  **Key Principle**

  Lifecycle is deployment state. Readiness is traffic-serving capability.

  **Use Readiness to decide whether to send traffic.**
</Note>


# Operating Dedicated Endpoint
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/operating



## Parameters Description

| Field                  | Type    | Required | Description                                                                                         |
| :--------------------- | :------ | :------- | :-------------------------------------------------------------------------------------------------- |
| `name`                 | string  | yes      | Display name for the endpoint                                                                       |
| `description`          | string  | no       | Optional description                                                                                |
| `model_name`           | string  | yes      | Template model name (e.g. `openai/gpt-oss-120b`)                                                    |
| `flavor_name`          | string  | yes      | Template flavor (e.g. `base`, `fast`)                                                               |
| `gpu_type`             | string  | yes      | GPU type supported by the chosen template + flavor                                                  |
| `gpu_count`            | integer | yes      | `gpu_count` per replica. Total maximum GPUs = `gpu_count × scaling.max_replicas`                    |
| `region`               | string  | yes      | `eu-north1`, `eu-west1`, `us-central1`                                                              |
| `scaling.min_replicas` | integer | yes      | Minimum replicas                                                                                    |
| `scaling.max_replicas` | integer | yes      | Maximum replicas                                                                                    |
| `enabled`              | boolean | no       | Enable / Disable the endpoint. Stops the endpoint with freeing up replicas, or starts the endpoint. |

## Update Endpoint Configuration

`PATCH` updates only the provided fields.

```http theme={null}
PATCH /v0/dedicated_endpoints/{endpoint_id}
```

<Note>
  Endpoint's region config `region` cannot be updated after dedicated endpoint creation.
</Note>

<CodeGroup>
  ```python Python theme={null}
  import os, json, requests

  CONTROL_PLANE_BASE_URL = "https://api.tokenfactory.nebius.com"
  API_TOKEN = os.environ["API_TOKEN"]
  endpoint_id = "<endpoint_id>"

  payload = {
      "name": "GPT-20B Endpoint (updated)",
      "scaling": {"min_replicas": 2, "max_replicas": 4},
  	"enabled": True
  }

  r = requests.patch(
      f"{CONTROL_PLANE_BASE_URL}/v0/dedicated_endpoints/{endpoint_id}",
      headers={"Authorization": f"Bearer {API_TOKEN}"},
      json=payload,
  )
  r.raise_for_status()
  print(json.dumps(r.json(), indent=2))
  ```

  ```shellscript cURL theme={null}
  curl -sS -X PATCH \
    "https://api.tokenfactory.nebius.com/v0/dedicated_endpoints/<endpoint_id>" \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "scaling": { "min_replicas": 2, "max_replicas": 4 }
    }'
  ```
</CodeGroup>

<Tip>
  Scaling changes may trigger provisioning of additional replicas. Plan for a short warm-up period where new replicas come online.
</Tip>

## List dedicated endpoints

```http theme={null}
GET /v0/dedicated_endpoints
```

<CodeGroup>
  ```python Python theme={null}
  import os, json, requests

  CONTROL_PLANE_BASE_URL = "https://api.tokenfactory.nebius.com"
  API_TOKEN = os.environ["API_TOKEN"]

  r = requests.get(
      f"{CONTROL_PLANE_BASE_URL}/v0/dedicated_endpoints",
      headers={"Authorization": f"Bearer {API_TOKEN}"},
  )
  r.raise_for_status()
  print(json.dumps(r.json(), indent=2))
  ```

  ```shellscript cURL theme={null}
  curl -sS \
    -H "Authorization: Bearer $API_TOKEN" \
    "https://api.tokenfactory.nebius.com/v0/dedicated_endpoints"
  ```
</CodeGroup>

## Delete endpoint

Deletes an endpoint permanently.

```http theme={null}
DELETE /v0/dedicated_endpoints/{endpoint_id}
```

<Warning>
  This is a permanent action. The GPUs associated with min\_replicas are released for other users.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  import os, requests

  CONTROL_PLANE_BASE_URL = "https://api.tokenfactory.nebius.com"
  API_TOKEN = os.environ["API_TOKEN"]
  endpoint_id = "<endpoint_id>"

  r = requests.delete(
      f"{CONTROL_PLANE_BASE_URL}/v0/dedicated_endpoints/{endpoint_id}",
      headers={"Authorization": f"Bearer {API_TOKEN}"},
  )
  print(r.status_code)
  r.raise_for_status()
  ```

  ```shellscript cURL theme={null}
  curl -sS -X DELETE \
    -H "Authorization: Bearer $API_TOKEN" \
    "https://api.tokenfactory.nebius.com/v0/dedicated_endpoints/<endpoint_id>"
  ```
</CodeGroup>


# Overview
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/overview



**Dedicated endpoints provide isolated, configurable deployments** of supported models and their performance templates. Use the control plane to create and manage deployments, and the data plane to run inference through OpenAI-compatible APIs.

With dedicated endpoints, you control:

<Card title="Region" icon="globe">
  Choose where your deployment runs to optimize latency and meet data residency requirements.
</Card>

<Card title="GPU configuration" icon="microchip">
  Select GPU type and GPUs per replica to match your performance and throughput needs.
</Card>

<Card title="Autoscaling" icon="arrow-down-arrow-up">
  Set minimum and maximum replicas to automatically scale capacity with traffic.
</Card>

<Card title="Lifecycle management" icon="circle">
  Create, update, stop, and delete deployments as your workloads evolve.
</Card>

## Key use cases:

* predictable capacity
* finetuned base model with custom weights
* compliance / private infra
* bigger control over deployment

## Dedicated vs Public Endpoints Comparison

| Feature                | Dedicated Endpoints                                                   | Public Serverless Endpoints                   |
| :--------------------- | :-------------------------------------------------------------------- | :-------------------------------------------- |
| Capacity               | Isolated capacity reserved for your organization                      | Shared multi-tenant capacity                  |
| Rate limits            | No standard rate limits; throughput depends on your deployed capacity | Dynamic rate limits apply                     |
| Data residency         | Deployment region is fixed and user-selected                          | Region may change based on available capacity |
| Autoscaling            | You control minimum and maximum replicas                              | Platform-managed with predefined limits       |
| Custom weights support | Supported for eligible models                                         | Base models only                              |
| Pricing                | Per GPU/hour, billed with per-minute granularity                      | Per token                                     |

## Learn more

<Card title="Deploy via API" icon="code" href="/ai-models-inference/dedicated-endpoints/deploy-api" />

<Card title="Deploy in UI" icon="arrow-pointer" href="/ai-models-inference/dedicated-endpoints/deploy-ui" />

<Card title="FAQ & Troubleshooting" icon="question" href="/ai-models-inference/dedicated-endpoints/faq" />


# Quickstart
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/quickstart



Dedicated endpoints can be deployed either:

* **Through the UI** — best for first-time users and exploration
* **Through the API** — best for automation, infrastructure-as-code, and repeatable workflows

### Before you begin:

* Make sure billing enabled and you have enough balance
* You have API key
* Supported model choosen

### Choose your path:

<Card title="Deploy in UI" icon="arrow-pointer" href="https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/deploy-ui" />

<Card title="Deploy in API" icon="code" href="https://docs.tokenfactory.nebius.com/ai-models-inference/dedicated-endpoints/deploy-api" />


# Function calling & Tools
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/function-calling

Learn how to make models select functions to extend their capabilities

Function calling allows you to enhance a model's capabilities by integrating it with external code, services, or APIs. You can define a set of functions—also referred to as tools—that the model can call. Based on the context provided in the conversation, the model can intelligently decide which functions to invoke and suggest appropriate arguments.

This capability enables you to build more powerful agents that can:

* Run custom code
* Retrieve real-time data
* Interact with third-party services
* Connect to MCP servers
* And perform other dynamic actions

<Note>
  **Important:** The model **does not execute** the functions itself. Instead, it outputs tool invocation instructions in an [OpenAI-compatible function calling format](https://platform.openai.com/docs/guides/function-calling). You are responsible for parsing these outputs and executing the corresponding functions on your backend or client side.
</Note>

<Steps>
  <Step title="Define Available Tools">
    Start by specifying the tools (functions) the model can use. Each tool is described using a JSON Schema that defines its name, input parameters, and expected data types. This schema informs the model how each tool should be invoked.
  </Step>

  <Step title="Model Determines Intent">
    When the model receives a user query, it analyzes the intent and decides how to respond. Based on the context and the tools available, it may:

    * Respond conversationally, or
    * Propose a function call by selecting a relevant tool and filling in the required arguments according to the schema.
  </Step>

  <Step title="Execute and Iterate">
    If a function call is proposed, your system is responsible for executing the function with the provided arguments. You then pass the function’s output back to the model as part of the next prompt. This allows the conversation to continue seamlessly, with the model incorporating the function result into its response or triggering further tool use.
  </Step>
</Steps>

## Limitations

The `tool_choice` parameter controls how the model selects which function (tool) to use. It determines whether the model should choose a tool automatically or follow an explicit instruction. Supported values include:

* `"auto"`\
  The model automatically selects the most appropriate function based on the context of the prompt. This is the default behavior and is useful for most use cases.
* **Explicit Function Call**\
  You can instruct the model to call a specific function using the following structure:
  ```json theme={null}
  {
    "type": "function",
    "function": {
      "name": "read_file"
    }
  }
  ```
  This forces the model to call the `read_file` function regardless of context, overriding its own tool selection logic.

## API Example

<CodeGroup>
  ```python Python expandable theme={null}

  import json
  import os

  from pydantic import BaseModel, Field
  from typing import Literal
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.getenv("NEBIUS_API_KEY")
  )

  model = "meta-llama/Meta-Llama-3.1-8B-Instruct-fast"

  class GetCurrentWeatherParams(BaseModel):
      city: str = Field(
          ...,
          description="The city to find the weather for, e.g. 'San Francisco'"
      )
      state: str = Field(
          ...,
          description=(
              "The two-letter abbreviation for the state that the city is in, "
              "e.g. 'CA' for California"
          )
      )
      unit: Literal['celsius', 'fahrenheit'] = Field(
          ...,
          description="The unit to fetch the temperature in"
      )

  tools = [{
      "type": "function",
      "function": {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": GetCurrentWeatherParams.model_json_schema()
      }
  }]

  messages = [
      {
          "role": "user",
          "content": "Hi! How are you doing today?"
      },
      {
          "role": "assistant",
          "content": "I'm doing well! How can I help you?"
      },
      {
          "role": "user",
          "content": (
              "Can you tell me what the temperature will be in Dallas, "
              "in Fahrenheit?"
          )
      }
  ]

  chat_completion = client.chat.completions.create(
      messages=messages,
      model=model,
      tools=tools,
      tool_choice={
          "type": "function",
          "function": {
              "name": "get_current_weather"
          }
      }
  )

  messages.append({
      "role": "assistant",
      "tool_calls": chat_completion.choices[0].message.tool_calls
  })

  # Simulate a tool call
  def get_current_weather(city: str, state: str, unit: 'str'):
      return (
        "The weather in Dallas, Texas is 85 degrees Fahrenheit. "
        "It is partly cloudy, with highs in the 90's."
      )


  available_tools = {"get_current_weather": get_current_weather}

  completion_tool_calls = chat_completion.choices[0].message.tool_calls
  for call in completion_tool_calls:
      tool_to_call = available_tools[call.function.name]
      args = json.loads(call.function.arguments)
      result = tool_to_call(**args)
      print(result)
      messages.append({
          "role": "tool",
          "content": result,
          "tool_call_id": call.id,
          "name": call.function.name
      })
  ```

  ```javascript JavaScript expandable theme={null}
  import OpenAI from 'openai';
  import { z } from 'zod';
  import { zodResponseFormat } from 'openai/helpers/zod';

  // 1. Define a schema using Zod. You can also define a JSON Schema directly;
  // see details after this code example

  const Weather = z.object({
    city: z.string(),
    state: z.string(),
    temperature: z.enum(["celsius", "fahrenheit"]),
  });

  // 2. Add the schema to your request

  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1/",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  const tools = [
    {
      type: "function",
      function: {
        name: "get_weather",
        parameters: zodResponseFormat(Weather, "weather").json_schema.schema,
      },
    }
  ];

  const response = await client.chat.completions.create({
    model: "meta-llama/Meta-Llama-3.1-8B-Instruct-fast",
    messages: [{"role": "user", "content": "Can you tell me what the temperature will be in Dallas, in Fahrenheit?"}],
    tools,
  });

  // 3. Work with the JSON output

  console.log(response.choices[0].message.tool_calls);
  ```
</CodeGroup>

Messages array with response:

```json expandable theme={null}
[
  {
    "role": "user",
    "content": "Hi! How are you doing today?"
  },
  {
    "role": "assistant",
    "content": "I'm doing well! How can I help you?"
  },
  {
    "role": "user",
    "content": "Can you tell me what the temperature will be in Dallas, in Fahrenheit?"
  },
  {
    "role": "assistant",
    "tool_calls": [
      {
        "id": "chatcmpl-tool-99a7259c139e4aa986549d07cde8df8f",
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "arguments": "{ \"city\" : \"Dallas\" , \"state\": \"Texas\", \"unit\": \"fahrenheit\" }"
        }
      }
    ]
  },
  {
    "role": "tool",
    "content": "The weather in Dallas, Texas is 85 degrees fahrenheit. It is partly cloudy, with highs in the 90's.",
    "tool_call_id": "chatcmpl-tool-99a7259c139e4aa986549d07cde8df8f",
    "name": "get_current_weather"
  }
]
```

## Try it in our Cookbook

<Card title="Function & Tool Calling Cookbook" icon="github" href="https://github.com/nebius/token-factory-cookbook/tree/main/tool-calling" />

## **Function calling** in Playground

You can explore Function Calling capabilities of models directly in the Playground:

1. **Go to the "Model Parameters" section.**
2. In the **"Function calling" section add function description**
3. **Enter your prompt and run it** to test whether the model returns the expected function selection for your use case.


# Structured output & JSON
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/json

Learn how to get structured output from our text models

## Overview

By default, a text generation model responds to your requests with a text in natural language. You can also force the model to respond with JSON instead, which makes it easier to work with outputs programmatically in your application.

For example, you can tell a model the name of an actor or actress and get a response with details of a film they have starred in, in a format like this:

```json theme={null}
{
  "title": "The Shining",
  "year": 1980,
  "director": "Stanley Kubrick",
  "cast": ["Jack Nicholson", "Shelley Duvall", "Danny Lloyd"],
}
```

Use `response_format`parameter to get JSON output. Depending on the settings in your request, the response can be:

* **JSON schema following.** Follows the specific schema you provide - `{"type": "json_schema"}` in `response_format `parameter.
* **Arbitrary JSON object.** Forces arbitrary JSON output, the model will decide on the schema by itself `{"type": "json_object"}` in `response_format `parameter.

<Info>
  **Supported models**\
  Some models are better in providing JSON due to their training data or our inference engine limitations. Use `JSON mode` tag in on a model card to find a model with structured output supported.
</Info>

<Steps>
  <Step title="Choose response format type">
    Select between strict `"json_schema"` and arbitrary `"json_object"`
  </Step>

  <Step title="Optionally: provide JSON schema">
    Provide the schema in a [JSON Schema Specification](https://json-schema.org/specification) compliant format.
  </Step>

  <Step title="Add instructions to the system or user prompt">
    It's always better to provide the instruction to follow JSON output and the schema to your model's system or user prompt to increase output quality and consistency
  </Step>

  <Step title="Test several models">
    Different models has different structured output capabilities. Always test and compare a few to obtain the best result
  </Step>
</Steps>

## JSON Schema following

JSON that follows a schema provided in your request. Make a request to the Nebius Token Factory API with `{"type": "json_schema"}` in `response_format `and provide desirable schema in a [JSON Schema Specification](https://json-schema.org/specification) compliant format.

<Tip>
  Many practical tests show that it's always better to provide the schema both in text prompt for the model and`"json_schema"`**parameter**
</Tip>

<CodeGroup>
  ```python Python expandable theme={null}
  import os
  import json
  from openai import OpenAI
  from typing import List, Literal
  from pydantic import BaseModel

  # 1. Define a schema using Pydantic's `BaseModel`. You can also define 
  # a JSON Schema directly; see details after this code example

  class Film(BaseModel):
    title: str
    year: int
    director: str
    cast: List[str]
    genre: Literal[
        "drama", "thriller", "sci-fi",
        "comedy", "horror", "fantasy"
    ]

  # 2. Add the schema to your request

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  completion = client.chat.completions.create(
      model="Qwen/Qwen3-235B-A22B",
  	response_format={
          	"type": "json_schema"
  			"json_schema": Film.model_json_schema()
      	}
      messages=[
          {
              "role": "system",
              "content": (
                  "I will give you an actor or actress, and you will respond "
                  "with details of a real film they have starred in, according "
                  "to the provided structure."
              )
          },
          {
              "role": "user",
              "content": "Jack Nicholson"
          }
      ],

  )

  # 3. Work with the JSON output or a refusal

  output = completion.choices[0].message
  if output.refusal:
      # Handle refusal
      print(output.refusal)
  elif output.content:
      try:
          output_json = json.loads(output.content)
          print(output_json)
          print("Film: {} ({})".format(output_json['title'], 
                                       output_json['year']))
          # etc.
      except Exception as e:
          # Handle possible exceptions, e.g. invalid JSON
          print(e)
          pass
  ```

  ```bash cURL expandable theme={null}
  # 1. Define a JSON Schema

  export SCHEMA='
  {
    "type": "object",
    "properties": {
      "title": {"type": "string"},
      "year": {"type": "integer"},
      "director": {"type": "string"},
      "cast": {
        "type": "array",
        "items": {"type": "string"}
      },
      "genre": {
        "enum": [
          "drama", "thriller", "sci-fi",
          "comedy", "horror", "fantasy"
        ]
      }
    },
    "required": ["title", "year", "director", "cast", "genre"]
  }
  '

  # 2. Add the schema to your request

  export OUTPUT=$(curl 'https://api.tokenfactory.nebius.com/v1/chat/completions' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: */*' \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    --data-binary '
      {
        "model": "mistralai/Mistral-Nemo-Instruct-2407",
        "messages": [
          {
            "role": "system",
            "content": "I will give you an actor or actress, and you will respond with details of a real film they have starred in, according to the provided structure."

          },
          {
            "role": "user",
            "content": "Jack Nicholson"
          }
        ],
        "response format": {
          	"type": "json_schema"
  			"json_schema": '"$SCHEMA"'
      	}  
      }
    '
  )

  # 3. Work with the JSON output or a refusal

  echo $OUTPUT | jq '
    .choices[0].message.refusal
    // (.choices[0].message.content | fromjson | .title)
  '
  ```

  ```javascript JavaScript expandable theme={null}
  import OpenAI from "openai";
  import { z } from "zod";
  import { zodResponseFormat } from "openai/helpers/zod";

  // 1. Define a schema using Zod. You can also define a JSON Schema directly;
  // see details after this code example

  const Film = z.object({
    title: z.string(),
    year: z.number(),
    director: z.string(),
    cast: z.array(z.string()),
    genre: z.enum(["drama", "thriller", "sci-fi", "comedy", "horror", "fantasy"]),
  });

  // 2. Add the schema to your request

  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1/",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  client.chat.completions.create({
    model: "openai/gpt-oss-120b",
    messages: [
      {
        role: "system",
        content: "I will give you an actor or actress, and you will respond with details of a real film they have starred in, according to the provided structure.",
      },
      {
        role: "user",
        content: "Jack Nicholson",
      },
    ],
    response_format: zodResponseFormat(Film, "film")
  })
  // 3. Work with the JSON output or a refusal
  .then((completion) => {
    const output = completion.choices[0].message;
    if (output.refusal) {
      // Handle refusal
      console.log(output.refusal);
    } else if (output.content) {
      try {
        const output_json = JSON.parse(output.content);
        console.log(`Film: ${output_json.title} (${output_json.year})`);
        // etc.
      } catch (e) {
        // Handle possible exceptions, e.g. invalid JSON
        console.log("An error occurred: ", e.message);
      }
    }
  });
  ```
</CodeGroup>

Example of a valid JSON schema:

```json expandable theme={null}
{
  "name": "meal_nutrition",
  "schema": {
    "type": "object",
    "properties": {
      "meal_name": {
        "type": "string",
        "description": "Name or description of the meal",
        "minLength": 1
      },
      "serving_size_g": {
        "type": "number",
        "description": "Serving size in grams",
        "minimum": 1
      },
      "nutrients": {
        "type": "object",
        "description": "Macronutrient and micronutrient content per serving",
        "properties": {
          "calories": {
            "type": "number",
            "description": "Energy in kilocalories (kcal)",
            "minimum": 0
          },
          "protein_g": {
            "type": "number",
            "description": "Protein in grams",
            "minimum": 0
          },
          "carbohydrates_g": {
            "type": "number",
            "description": "Carbohydrates in grams",
            "minimum": 0
          },
          "fat_g": {
            "type": "number",
            "description": "Total fat in grams",
            "minimum": 0
          },
          "fiber_g": {
            "type": "number",
            "description": "Dietary fiber in grams",
            "minimum": 0
          },
          "sugars_g": {
            "type": "number",
            "description": "Sugars in grams",
            "minimum": 0
          },
          "sodium_mg": {
            "type": "number",
            "description": "Sodium in milligrams",
            "minimum": 0
          }
        },
        "required": [
          "calories",
          "protein_g",
          "carbohydrates_g",
          "fat_g",
          "fiber_g",
          "sugars_g",
          "sodium_mg"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "meal_name",
      "serving_size_g",
      "nutrients"
    ],
    "additionalProperties": false
  },
  "strict": true
}
```

## Arbitrary JSON object

The model will produce a valid JSON object without following any specific schema.\
Make a request to the Nebius Token Factory API with `{"type": "json_object"}` in `response_format`:

<CodeGroup>
  ```python Python expandable theme={null}
  import os
  import json
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  completion = client.chat.completions.create(
      model="openai/gpt-oss-120b",
      # 1. Instruct the model to produce JSON. In this example, we do it 
      # in the system prompt; you can do it in a user message instead
      messages=[
          {
              "role": "system",
              "content": (
                  "I will give you an actor or actress, and you will respond "
                  "with details of a real film they have starred in, using JSON "
                  "as the format."
              )
          },
          {
              "role": "user",
              "content": "Jack Nicholson"
          }
      ],
      # 2. Set the response format to `json_object`
      response_format={
          "type": "json_object"
      }
  )

  # 3. Work with the JSON output (it should be valid but is not guaranteed 
  # to have any predetermined fields) or a refusal

  output = completion.choices[0].message
  if output.refusal:
      # Handle refusal
      print(output.refusal)
  elif output.content:
      try:
          output_json = json.loads(output.content)
          print(output_json)
      except Exception as e:
          # Handle possible exceptions, e.g. invalid JSON
          print(e)
          pass
  ```

  ```bash cURL expandable theme={null}
   # 1. Instruct the model to produce JSON. In this example, we do it in the system prompt; 
   # you can do it in a user message instead
   # 2. Set the response format to `json_object`

  export OUTPUT=$(curl 'https://api.tokenfactory.nebius.com/v1/chat/completions' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: */*' \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    --data-binary '
      {
        "model": "mistralai/Mistral-Nemo-Instruct-2407",
        "messages": [
          {
            "role": "system",
            "content": "I will give you an actor or actress, and you will respond with details of a real film they have starred in, using JSON as the format."
          },
          {
            "role": "user",
            "content": "Jack Nicholson"
          }
        ],
        "response_format": {
          "type": "json_object"
        }
      }
    '
  )

  # 3. Work with the JSON output (it should be valid but is not guaranteed 
  # to have any predetermined fields) or a refusal

  echo $OUTPUT | jq '
    .choices[0].message.refusal 
    // (.choices[0].message.content | fromjson)
  '
  ```

  ```javascript JavaScript expandable theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.tokenfactory.nebius.com/v1/',
    apiKey: process.env.NEBIUS_API_KEY,
  });

  client.chat.completions.create({
    model: "mistralai/Mistral-Nemo-Instruct-2407",
    // 1. Instruct the model to produce JSON. In this example, we do it in the system prompt; 
    // you can do it in a user message instead
    messages: [
      {
        role: "system",
        content: "I will give you an actor or actress, and you will respond with details of a real film they have starred in, using JSON as the format.",
      },
      {
        role: "user",
        content: "Jack Nicholson",
      },
    ],
    // 2. Set the response format to `json_object`
    response_format: {
      type: "json_object",
    },
  })
  // 3. Work with the JSON output (it should be valid but is not guaranteed 
  // to have any predetermined fields) or a refusal
  .then((completion) => {
    const output = completion.choices[0].message;
    if (output.refusal) {
      // Handle refusal
      console.log(output.refusal);
    } else if (output.content) {
      try {
        const output_json = JSON.parse(output.content);
        console.log(output_json);
      } catch (e) {
      // Handle possible exceptions, e.g. invalid JSON
      console.log("An error occurred: ", e.message);
      }
    }
  });
  ```
</CodeGroup>

<Tip>
  Use **JSON schema instead of JSON objects** whenever you need **strict JSON structure**
</Tip>

## Try it in our Cookbook

<Card title="Strucrured output - Cookbook" icon="github" href="https://github.com/nebius/token-factory-cookbook/blob/main/guided_json.ipynb" />

## Structured output in Playground

You can explore the structured output capabilities of models directly in the Playground:

1. **Go to the "Model Parameters" section.**
2. ****`In the "Response format" dropdown, select JSON object/schema.`****
3. *(Optional)* **Provide a strict JSON schema** if you want the model to follow a specific structure.
4. **Enter your prompt and run it** to test whether the model returns the expected JSON output for your use case.


# Inference Observability
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/observability



Inference Observability provides real-time and historical metrics for your inference workloads, including latency, throughput, scaling, and error rates. It helps you debug performance issues, benchmark models, and understand capacity behavior of dedicated or public endpoints.

You can access Observability from:

**Navigation Bar → Inference → Observability**

<Note>
  Observability Metrics are **only accessible for Dedicated Endpoints inference**
</Note>

## What you can do with Observability

Inference Observability is designed to help you answer practical engineering questions - debug, optimise and operate:

* When and why did latency increase?
* Are errors coming from my requests or infrastructure?
* Compare performance across endpoints
* Understand token throughput and response times
* Monitor scaling behavior and capacity

## Metrics available

### Traffic

These metrics describe how much load your endpoint is handling and understand traffic spikes, prompt size trends, throughput limits

| Metric                    | Description                                                                                                       |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------- |
| Requests per minute       | Number of requests sent to the API                                                                                |
| Input tokens per minute   | Incoming tokens processed                                                                                         |
| Output tokens per minute  | Tokens generated by models                                                                                        |
| Input tokens per request  | Distribution of prompt sizes                                                                                      |
| Output tokens per request | Distribution of response sizes                                                                                    |
| KV-cache hit rate         | Percentage of prefix cache lookups that were served from cache.<br />Includes both local and external cache hits. |

### Latency

Latency metrics describe how long requests take at different stages. This helps identify model warmup effects, queueing or scaling delays, slow generation behavior. Latency charts display percentiles: `p50`, `p90`, `p99`

<Note>
  TTFT (Time to First Token) metric is measured across **streaming requests only**
</Note>

| Metric                     | Description                                                                             |
| :------------------------- | :-------------------------------------------------------------------------------------- |
| End-to-end latency         | Time from request sent to full response received                                        |
| TTFT (Time to First Token) | Time until the first token is generated. <br />Measured across streaming requests only. |
| Output speed (TPS)         | Tokens generated per second                                                             |

### Autoscaling and Capacity

These metrics help explain why latency increases under load and whether scaling is working as expected, as well as if replicas are well utilized with the workload. Some capacity metrics may be hidden depending on your pricing model.

| Metric                   | Description                                                                                         |
| :----------------------- | :-------------------------------------------------------------------------------------------------- |
| Active replicas          | Currently running replicas                                                                          |
| Active GPUs              | Number of active GPUs at the moment                                                                 |
| GPU utilisation, avg     | This metric represents the fraction of time the GPU was active.<br />Average across all replicas.   |
| GPU utilisation, busiest | This metric represents the fraction of time the GPU was active.<br />Value for the busiest replica. |

### Errors and success rate

| Metric                    | Description                                          |
| :------------------------ | :--------------------------------------------------- |
| Error rate by status code | Percentage of failed requests grouped by HTTP status |

Typical error classes:

* 4xx — invalid requests or limits
* 429 — rate limiting or capacity limits
* 5xx — internal errors

This helps you quickly see:

* Whether failures come from traffic patterns
* Whether rate limits are reached
* Whether infrastructure issues occurred

<Note>
  Looking for an incident history or having a down time? You can also check Token Factory section at [Nebius Cloud status page](https://status.nebius.com)
</Note>

***

## Filters and dimensions

You can filter metrics to narrow down specific traffic patterns. This makes it possible to compare regions, projects and benchmark endpoints. Filters apply to all charts simultaneously.

| Filter         | Purpose                              |
| :------------- | :----------------------------------- |
| Time range     | Analyze recent or historical traffic |
| Model endpoint | Compare endpoints                    |
| Project        | Analyze per-project usage            |
| API key        | Identify individual clients          |
| Region         | Compare cross-region performance     |
| Error code     | Debug failures                       |
| Prompt length  | Compare short vs long prompts        |
| Latency range  | Focus on slow requests               |

***

## Exporting metrics and API access

The Monitoring service provides metrics in Nebius Token Factory in two forms:

* Preconfigured [dashboards](https://tokenfactory.nebius.com/observability) in the web UI show key metrics for each resource.
* The API to metrics is available via [Prometheus](https://docs.nebius.com/observability/metrics/prometheus) and [Grafana®](https://docs.nebius.com/observability/metrics/grafana) integrations. You can filter and visualize the metrics the way you want with API integration.

<Card title="Observability API integrations" icon="arrow-right-to-bracket" href="https://docs.tokenfactory.nebius.com/ai-models-inference/observability-api-integrations">
  Go to Observability API access to learn more how to integrate with Prometheus and Grafana
</Card>

***

## How metrics are calculated

Metrics are aggregated in short windows and refreshed continuously. The aggregation window depends on the timeline choosen.

Typical characteristics:

* Near-real-time updates (usually within tens of seconds)
* Percentile-based latency statistics
* Rolling aggregation windows depending on the time scale choosen

<Note>
  Observability dashboards are intended for operational debugging and performance analysis, not billing reconciliation.
</Note>

***

## Access control

Observability is a project-nested entity and follows project permissions.

| Role                         | Access                                    |
| :--------------------------- | :---------------------------------------- |
| Organization Admin           | View all projects and their observability |
| Organisation Billing Manager | No access to observability                |
| Project Admin                | View project observability                |
| Project Member               | View project observability                |

***

## FAQ

### Data retention and deletion

Observability data is tied to the project lifecycle. When a project is deleted associated observability data is automatically removed.

### Regions and data locality

Projects may contain endpoints in multiple regions. Metrics are collected in the region where inference runs, but eventually stored at `eu-north`region. Filters allow you to compare endpoints data in different regions


# Observability API integrations
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/observability-api-integrations



## How to connect Prometheus

<Note>
  Prometheus can only show a limited amount of monitoring data. If you have a large infrastructure, consider connecting a data source in Grafana® instead
</Note>

1. Issue a [static API key in Nebius Token Factory UI](https://tokenfactory.nebius.com/project/api-keys).
2. [Download the latest release](https://prometheus.io/download) of Prometheus for your platform.
3. Extract the contents and switch to the folder with Prometheus:

   ```
   tar xvfz prometheus-***.tar.gz
   cd prometheus-***
   ```
4. Create the `prometheus.yml` configuration file that configures Prometheus to retrieve Monitoring metrics. Use one of the following configurations depending on your Prometheus version:

<CodeGroup>
  ```yaml Prometheus 3 theme={null}
  scrape_configs:
    - job_name: 'Export time series from Nebius Monitoring'
      honor_labels: true
      scrape_interval: 15s
      scheme: https
      metrics_path: '/projects/<project_ID>/service-provider/prometheus/federate'
      params:
        match[]:
          - '{__name__=~".+"}'
      bearer_token: '<static_API_key>'
      static_configs:
        - targets:
          - 'read.monitoring.api.nebius.cloud'
  ```

  ```yaml Prometheus 2 theme={null}
  scrape_configs:
    - job_name: 'Export time series from Nebius Monitoring'
      honor_labels: true
      scrape_interval: 15s
      scheme: https
      metric_name_validation_scheme: legacy
      scrape_protocols:
        - OpenMetricsText0.0.1
      metrics_path: '/projects/<project_ID>/service-provider/prometheus/federate'
      params:
        match[]:
          - '{__name__=~".+"}'
      bearer_token: '<static_API_key>'
      static_configs:
        - targets:
          - 'read.monitoring.api.nebius.cloud'
  ```
</CodeGroup>

In this file, change the following parameters:

* `bearer_token`: enter the static key that you [got earlier.](https://tokenfactory.nebius.com/project/api-keys)
* `metrics_path`: specify your project ID in the URL.

  To get the project ID, go to the [Nebius Token Factory UI →  Project settings](https://tokenfactory.nebius.com/project/). Under the project's name, click  → **Copy project ID**.
* `match[]`: optionally specify which data Prometheus collects by filtering for labels or metric names. For example, to collect only metrics with the `disk` prefix, set the following value:

  ```yaml theme={null}
  match[]:
    - '{__name__=~"^disk.*"}'
  ```
* `scrape_interval`: you can change the interval, but the recommended interval is no less than 15 seconds.

Start Prometheus:

```
./prometheus --config.file=prometheus.yml
```

### How to connect Grafana data source

To view visualized metrics in Grafana dashboards, connect Grafana to Monitoring and query the data by using [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/).

1. Make sure that you have Grafana available, in any of these ways:
   * [Install Grafana on your local machine](https://grafana.com/docs/grafana/latest/setup-grafana/installation/).
   * [Create an account in Grafana Cloud](https://grafana.com/auth/sign-up/create-user).
2. Open Grafana in your browser.
3. In the side menu, select **Connections** → **Data sources**.
4. In the top right corner, click **Add new data source**.
5. Select **Prometheus**.
6. In the Prometheus configuration, enter the following settings:
   * **Connection** → **Prometheus server URL**: `https://read.monitoring.api.nebius.cloud/projects/<project_ID>/service-provider/prometheus`. Specify your project ID in the URL. You can get it on the [Project settings](https://console.nebius.com/settings) page of the web console.
   * **Authentication** → **HTTP headers**: click **Add header** and enter `Authorization` and the value of the static key that you [got earlier](https://docs.nebius.com/observability/metrics/grafana#prerequisites).
7. Click **Save and test**. If Prometheus is connected successfully, you should see the "Successfully queried the Prometheus API" message.


# Overview
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/overview

Get an inference engine overview

With Nebius Token Factory, you can test and deploy open-source AI models for generative language processing tasks, such as building virtual assistants and chatbots.

## Available models

Nebius Token Factory supports the following model types:

<Columns>
  <Card title="Text-to-text" icon="comments" href="https://tokenfactory.nebius.com/endpoints?modality=text2text" />

  <Card title="Embedding" icon="grid-round-4" href="https://tokenfactory.nebius.com/endpoints?modality=embedding" />

  <Card title="Vision" icon="eye" href="https://tokenfactory.nebius.com/endpoints?modality=image2text" />
</Columns>

See the full list of available models in [Nebius Token Factory](http://tokenfactory.nebius.com/).

## Model flavors

Inference performance is determined by how the endpoint is configured - balancing:

* Batch size
* GPU type (L40, H100, H200, B200)
* GPU count
* Inference-time optimizations (e.g., speculative decoding)

To cover common usage patterns, **two model flavors are available:**

<Columns>
  <Card title="Base" icon="coin" />

  <Card title="Fast" icon="bolt" />
</Columns>

Both deliver identical model outputs. Differences lie in token pricing, latency, and the level of applied optimizations.

The Fast flavor uses smaller batch sizes, increased compute allocation, and techniques such as speculative decoding to reduce latency and improve responsiveness.

To use the Fast flavor, append `-fast` to the model name in the [API](https://docs.tokenfactory.nebius.com/api-reference/introduction).

These flavors are curated based on infrastructure and model-level expertise. For more specific needs - such as strict latency budgets, cost-efficiency targets, or high-throughput applications - endpoint configurations can be tailored to the customer use case through direct collaboration with the sales and solutions engineering team.

## Inference optimisations

Our LLM inference service employs a range of optimization techniques to increase throughput while maintaining model quality. These techniques include:

<Columns>
  <Card title="KV Cache" icon="gear">
    A caching mechanism that stores frequently accessed key-value pairs, reducing the number of computations required.
  </Card>

  <Card title="Paged Attention" icon="gear">
    A technique that divides the input sequence into smaller chunks, processing each chunk separately to reduce memory usage and computation.
  </Card>

  <Card title="Flash Attention" icon="gear">
    A modified attention mechanism that reduces the number of computations required for attention calculations.
  </Card>

  <Card title="Quantization" icon="gear">
    A technique that reduces the precision of model weights and activations, decreasing memory usage and computation.
  </Card>

  <Card title="Continuous Batching" icon="gear">
    A method that batches multiple input sequences together, increasing throughput by reducing the overhead of individual requests.
  </Card>

  <Card title="Context Caching" icon="gear">
    A caching mechanism that stores the context (i.e., the output of previous layers) for each input sequence, reducing the number of computations required.
  </Card>

  <Card title="Speculative decoding" icon="gear">
    An advanced technique that uses auxiliary models to pre-generate likely next tokens. The main model verifies these predictions, reducing the number of forward passes required and improving throughput without degrading output quality.
  </Card>
</Columns>

### **Impact on model quality**

Our optimization techniques are designed to minimize the impact on model quality. Through extensive testing and evaluation, we have found that our optimized models maintain approximately 99% of the original model's quality.

This means that the optimized models produce nearly identical results to the original models, with only minor differences in output.The quality impact of each optimization technique is carefully evaluated and monitored to ensure that the cumulative effect of all techniques does not compromise the overall quality of the model. Our goal is to provide a high-throughput inference service that delivers accurate and reliable results, while minimizing the computational resources required.

## Generation parameters

You can tune the model’s **generation parameters** to adapt outputs for your use case and optimize performance or cost. Nebius Token Factory supports most of OpenAI compatible generation parameters.

Supported parameters vary by interface:

* **Playground** - Supports the most commonly used parameters.
* **API** - Supports the full set of vLLM parameters.

To view additional model parameters, please refer to this [section](https://docs.tokenfactory.nebius.com/api-reference/examples/list-of-models).


# UI & Playground
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/playground



The [**Playground**](https://tokenfactory.nebius.com/playground) in Nebius Token Factory lets you experiment with available AI models through a web interface — no coding required.

## Model card

In the Nebius Token Factory UI, each **model card** displays key parameters for the model:

* **Input tokens** — Price per token included in an API request, shown in USD per million tokens.
* **Output tokens** — Price per token generated by the model (returned in the API response), in USD per million tokens.
* **Tokens per second** — Approximate generation speed of the model in tokens per second. Actual performance may vary.
* **Quality** — MMLU score reported by the model provider.

To view an extended list of model parameters via the API, send a request to the **List models** endpoint with the query parameter `verbose=true`.

## Using the playground

1. On the [**Models**](https://tokenfactory.nebius.com/) page, find the model you want to try and click **Go to playground** on its card.
2. Under **System prompt**, enter instructions that guide the model’s behavior. You can add **few-shot examples** to demonstrate the desired output format.
3. Start chatting with the model and refine your setup as needed.

Saving your setup:

* **Export as code** — Click **View code** in the left panel to copy your model setup (including the chat) for use in your application.
* **Save as a prompt preset** — Click **Save preset** in the left panel to store your setup for later use or sharing.

## **Compare setups**

To work with two model setups side by side, click **Compare**. This will open two chat windows where you can submit inputs for both setups at the same time.

You can also synchronize model parameters and system prompts between the two chats. To do this, click **Copy to right** or **Copy to left** in the **Parameters** menu or next to a system prompt.

<Note>
  If the models have different sets of parameter, synchronization may not be possible.
</Note>

To go back to the single-model mode, close one of the chats. The remaining chat will keep its setup and history.

## **View code**

You can copy your model setup and chat as code to continue working with them in your application:

* Single-model mode: next to **Compare**, click → **View code**.
* Compare mode: Next to **Parameters**, click <Icon icon="circle-ellipsis-vertical" /> icon → in dropdown list select → **View code**.


# Rate Limits & Scaling
Source: https://docs.tokenfactory.nebius.com/ai-models-inference/rate-limits

Learn how rate limiting of requests works and what are the scaling rules

Nebius AI Inference is elastic by design. When you gradually increase your workload we scale the capacity with you. Most teams on Startup Tier never need to think about rate limits—but when you start pushing tens of thousands of requests per minute it helps to know how the platform behaves. Sudden bursts of AI Model traffic may be subject to throttling. This page explains the **dynamic rate‑limiting** system, how it auto‑scales, and the knobs you can turn when you need more headroom.

<Tip>
  **Need unlimited throughput?**\
  If you have sustained workloads that dwarf the standard limits, [reach out to us to upgrade to the Enterprise Tier](https://nebius.com/?_gl=1*1ni0ub9*_gcl_au*OTY2MTI0ODU5LjE3NTA4MzkxODkuOTQxMDE3MTg3LjE3NTEwMTgyMjYuMTc1MTAxODIyNg..#ai-contact-form). Enterprise removes the soft caps described below and gives you dedicated capacity plus an SLA.
</Tip>

### How it works

Key idea – Limits are dynamic. If your app stays close to the ceiling, we automatically raise it. If traffic falls off, we scale it back.

Every user is provided with a default rate limit cap. This limit grows automatically when you consistently operate close to your capacity and current limit.

<Tip>
  You can find the defaults at Rate Limits section of [Nebius Token Factory](https://tokenfactory.nebius.com/project/rate-limits)
</Tip>

We evaluate usage in rolling 15‑minute buckets:

* **Scale‑up rule** – When **average** usage in a 15‑minute window ≥ 80 % of the current limit, the limit for the *next* window increases by 20 % (`× 1.2`).
* **Scale‑down rule** – When average usage in a 15‑minute window ≤ 50 %, the limit for the next window decreases by one‑third (`÷ 1.5`).
* **Hard ceiling** – The limit can grow to **20 ×** your base allocation. Beyond that we require an Enterprise plan.

Visual example, assuming you continue to drive ≥ 80 % utilisation each window:

| **Window** | **Scale factor** | **RPM limit** | **TPM limit** |
| :--------- | :--------------- | :------------ | :------------ |
| Baseline   | `1.00×`          | 60            | 400,000       |
| + 15 min   | `1.20×`          | 72            | 480,000       |
| + 30 min   | `1.44×`          | 86            | 576,000       |
| + 1 h      | `2.07×`          | 124           | 828,000       |
| + 2 h      | `4.30×`          | 258           | 1,720,000     |

### Monitoring your headroom and handling 429s

Your current rate limits are always visible in the API response headers, which are detailed further down.

If you exceed the active limit you will receive **HTTP 429**. To avoid this, you can track your consumption against your limits using the `x-ratelimit-remaining-requests` and `x-ratelimit-remaining-tokens` response headers.

<Tip>
  **Use Batch API for async workloads - it has significantly higher limits. Read more**
</Tip>

### **Over-the-Limit Processing**

In some cases, requests that exceed your rate limit may still be processed. This occurs when the system has spare capacity available, and your request can be handled with a lower priority without affecting other users.

These responses include:

```text theme={null}
x-ratelimit-over-limit: yes
```

This indicates that while your request was successful, you are over your nominal limit, and subsequent requests may be throttled if you continue to exceed your quota. Treat this as an early warning—subsequent calls may be throttled.

### Rate Limit Response Headers

Here's a simple explanation of response headers you can use to track you limits quotas:

<Expandable title="Description of Rate Limits response headers">
  | Header                                      | Description                                                                                                                                                                                                                            |
  | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `x-ratelimit-limit-requests`                | The maximum number of requests that are permitted per minute.                                                                                                                                                                          |
  | `x-ratelimit-limit-tokens`                  | The maximum number of tokens that are permitted per minute.                                                                                                                                                                            |
  | `x-ratelimit-remaining-requests`            | The remaining number of requests that are permitted before exhausting the rate limit.                                                                                                                                                  |
  | `x-ratelimit-remaining-tokens`              | The remaining number of tokens that are permitted before exhausting the rate limit. Note that the limit is replenished continuously. If your usage is sustainably below the rate limit, this number will hover near its maximum value. |
  | `x-ratelimit-reset-requests`                | The time in seconds until the rate limit (based on requests) resets.                                                                                                                                                                   |
  | `x-ratelimit-reset-tokens`                  | The time in seconds until the rate limit (based on tokens) resets.                                                                                                                                                                     |
  | `x-ratelimit-dynamic-scale-requests`        | The current dynamic scale factor applied to your request rate limit.                                                                                                                                                                   |
  | `x-ratelimit-dynamic-scale-tokens`          | The current dynamic scale factor applied to your token rate limit.                                                                                                                                                                     |
  | `x-ratelimit-dynamic-period-remaining`      | The time in seconds until the next dynamic rate limit adjustment.                                                                                                                                                                      |
  | `x-ratelimit-dynamic-period-usage-requests` | Your average request usage in the current adjustment period, as a percentage.                                                                                                                                                          |
  | `x-ratelimit-dynamic-period-usage-tokens`   | Your average token usage in the current adjustment period, as a percentage.                                                                                                                                                            |
  | `x-ratelimit-over-limit`                    | Set to "yes" if a request that is over the limit is processed. This happens when the system has spare capacity, and the request is handled with a lower priority.                                                                      |
  | `Retry-After`                               | The time in seconds to wait before making another request if the rate limit is exceeded.                                                                                                                                               |
</Expandable>


# Cancel a multipart upload
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/cancel-a-multipart-upload

https://api.tokenfactory.nebius.com/openapi.json post /v1/datasets/uploads/{upload_id}/cancel
Cancel a multipart upload



# Complete a multipart upload, create a new dataset
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/complete-a-multipart-upload-create-a-new-dataset

https://api.tokenfactory.nebius.com/openapi.json post /v1/datasets/uploads/{upload_id}/complete
Complete a multipart upload



# Create a dataset by uploading data
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/create-a-dataset-by-uploading-data

https://api.tokenfactory.nebius.com/openapi.json post /v1/datasets
Create a dataset



# Create a new multipart upload for a dataset
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/create-a-new-multipart-upload-for-a-dataset

https://api.tokenfactory.nebius.com/openapi.json post /v1/datasets/uploads
Create a new upload



# Delete a dataset
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/delete-a-dataset

https://api.tokenfactory.nebius.com/openapi.json delete /v1/datasets/{dataset_id}
Delete a dataset



# Filter operations by attributes
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/filter-operations-by-attributes

https://api.tokenfactory.nebius.com/openapi.json get /v1/operations
List operations



# Get a list of datasets in project
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-a-list-of-datasets-in-project

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets
List datasets



# Get dataset info
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-dataset-info

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets/{dataset_id}
Get dataset info



# Get dataset query template
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-dataset-query-template

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets/{dataset_id}/query_templates
Get dataset query template



# Get information about a multipart upload
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-information-about-a-multipart-upload

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets/uploads/{upload_id}
Get upload information



# Get operation errors
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-operation-errors

https://api.tokenfactory.nebius.com/openapi.json get /v1/operations/{operation_id}/errors
Get errors for a given failed operation.



# Get operation info by id
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-operation-info-by-id

https://api.tokenfactory.nebius.com/openapi.json get /v1/operations/{operation_id}
Get operation info



# Get operation results
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/get-operation-results

https://api.tokenfactory.nebius.com/openapi.json get /v1/operations/{operation_id}/results
Get checkpoints for a fine-tuning operation or the output file id for a dataset-to-file operation.



# List parts of a multipart upload
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/list-parts-of-a-multipart-upload

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets/uploads/{upload_id}/parts
List upload parts



# Patch dataset info
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/patch-dataset-info

https://api.tokenfactory.nebius.com/openapi.json patch /v1/datasets/{dataset_id}
Partially update dataset info



# Read dataset content
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/read-dataset-content

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets/{dataset_id}/content
Get dataset content



# Read dataset content as csv or jsonl
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/read-dataset-content-as-csv-or-jsonl

https://api.tokenfactory.nebius.com/openapi.json get /v1/datasets/{dataset_id}/export
Export dataset content



# Run operation
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/run-operation

https://api.tokenfactory.nebius.com/openapi.json post /v1/operations
Create an operation



# Stop operation by id
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/stop-operation-by-id

https://api.tokenfactory.nebius.com/openapi.json post /v1/operations/{operation_id}/cancel
Cancel operation



# Upload a new part for a multipart upload
Source: https://docs.tokenfactory.nebius.com/api-reference/datasets/upload-a-new-part-for-a-multipart-upload

https://api.tokenfactory.nebius.com/openapi.json post /v1/datasets/uploads/{upload_id}/parts
Upload a new part



# Create Dedicated Endpoint
Source: https://docs.tokenfactory.nebius.com/api-reference/dedicated-endpoints/create-dedicated-endpoint

https://api.tokenfactory.nebius.com/openapi.json post /v0/dedicated_endpoints



# Delete Dedicated Endpoint
Source: https://docs.tokenfactory.nebius.com/api-reference/dedicated-endpoints/delete-dedicated-endpoint

https://api.tokenfactory.nebius.com/openapi.json delete /v0/dedicated_endpoints/{endpoint_id}



# List Dedicated Endpoint Templates
Source: https://docs.tokenfactory.nebius.com/api-reference/dedicated-endpoints/list-dedicated-endpoint-templates

https://api.tokenfactory.nebius.com/openapi.json get /v0/dedicated_endpoints/templates



# List Dedicated Endpoints
Source: https://docs.tokenfactory.nebius.com/api-reference/dedicated-endpoints/list-dedicated-endpoints

https://api.tokenfactory.nebius.com/openapi.json get /v0/dedicated_endpoints



# Update Dedicated Endpoint
Source: https://docs.tokenfactory.nebius.com/api-reference/dedicated-endpoints/update-dedicated-endpoint

https://api.tokenfactory.nebius.com/openapi.json patch /v0/dedicated_endpoints/{endpoint_id}



# Create embeddings
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/create-embeddings



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

Request:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  client.embeddings.create(
      model="BAAI/bge-en-icl",
      input="Wake up, Neo...",
      encoding_format="float"
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.tokenfactory.nebius.com/v1/embeddings \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "BAAI/bge-en-icl",
      "input": "Wake up, Neo...",
      "encoding_format": "float"
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```text theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "embedding",
        "embedding": [
          0.0023064255,
          -0.009327292,
          .... (1536 floats total for BAAI/bge-en-icl)
          -0.0028842222,
        ],
        "index": 0
      }
    ],
    "model": "BAAI/bge-en-icl",
    "usage": {
      "prompt_tokens": 8,
      "total_tokens": 8
    }
  }
  ```
</Accordion>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).


# Files
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/files



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

## **Upload a file: POST**

Request:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  batch_requests = client.files.create(
      file=open("batch-requests.jsonl", "rb"),
      purpose="batch"
  )
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/files \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    -F purpose="batch" \
    -F file="@batch-requests.jsonl"
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "id": "file-123",
    "object": "file",
    "bytes": 120000,
    "created_at": 1730723658,
    "filename": "batch-requests.jsonl",
    "purpose": "batch"
  }
  ```
</Accordion>

## **Get file info: GET**

Request:

<CodeGroup>
  ```python Python theme={null}
  client.files.retrieve("file-123")
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/files/file-123 \
    -H "Authorization: Bearer $NEBIUS_API_KEY"
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "id": "file-123",
    "object": "file",
    "bytes": 120000,
    "created_at": 1730723658,
    "filename": "batch-requests.jsonl",
    "purpose": "batch"
  }
  ```
</Accordion>

## **Get file content: GET**

Request:

<CodeGroup>
  ```python Python theme={null}
  batch_result = client.files.content("file-123")
  print(batch_result.text)
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/files/file-123/content \
    -H "Authorization: Bearer $NEBIUS_API_KEY" > batch_result.jsonl
  ```
</CodeGroup>

## **List files: GET**

Request:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  client.files.list()
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/files \
    -H "Authorization: Bearer $NEBIUS_API_KEY"
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "data": [
      {
        "id": "file-123",
        "object": "file",
        "bytes": 120000,
        "created_at": 1730723658,
        "filename": "batch-requests.jsonl",
        "purpose": "batch"
      },
      {
        "id": "file-789",
        "object": "file",
        "bytes": 120,
        "created_at": 1731493853,
        "filename": "health-records-batch.jsonl",
        "purpose": "batch"
      }
    ],
    "object": "list"
  }
  ```
</Accordion>

## **Delete a file: DELETE**

Request:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  client.files.delete("file_123")
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/files/file_123 \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    -X DELETE
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "id": "batch_123",
    "object": "file",
    "deleted": true
  }
  ```
</Accordion>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).


# Image generation
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/image-generation



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

Request:

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI
  import os

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  completion = client.images.generate(
      model="stability-ai/sdxl",
      prompt="An elephant in a desert",
      response_format="b64_json",
      extra_body={
          "response_extension": "png",
          "width": 512,
          "height": 512,
          "num_inference_steps": 30,
          "seed": -1,
          "negative_prompt": "Giraffes, night sky"
      }
  )

  print(completion.to_json())
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/images/generations \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "stability-ai/sdxl",
      "prompt": "An elephant in a desert",
      "response_format": "b64_json",
      "response_extension": "webp",
      "width": 512,
      "height": 512,
      "num_inference_steps": 30,
      "seed": -1,
      "negative_prompt": "Giraffes, night sky"
    }'
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  const response = await client.images.generate({
    model: 'black-forest-labs/flux-schnell',
    response_format: 'b64_json',
    width: 1024,
    height: 768,
    response_extension: 'png',
    num_inference_steps: 4,
    negative_prompt:
      'Giraffes, night sky',
    seed: -1,
    prompt: 'An elephant in a desert',
  }).then((completion) => {
    console.log(completion.data);
  });
  ```
</CodeGroup>

<Accordion title="Response">
  <CodeGroup>
    ```Non-verbose Response format: b64_json theme={null}
    {
      "data": [
        {
          "b64_json": "UklGRg66Ag..."
        }
      ],
      "id": "text2img-0941c39c-..."
    }
    ```

    ```Verbose Response format: url theme={null}
    {
      "data": [
        {
          "url": "https://pictures-storage-dev.storage.eu-north1.nebius.cloud/text2img-0941c39c-....webp"
        }
      ],
      "id": "text2img-0941c39c-..."
    }
    ```
  </CodeGroup>
</Accordion>

<Note>
  Save the image once you receive the link. Nebius Token Factory does not store the image from the provided link permanently.
</Note>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).


# List of models
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/list-of-models



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

Request:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  client.models.list()
  ```

  ```bash cURL theme={null}
  curl https://api.tokenfactory.nebius.com/v1/models \
    -H "Authorization: Bearer $NEBIUS_API_KEY"
  ```
</CodeGroup>

<Accordion title="Response">
  <CodeGroup>
    ```Non-verbose Non-verbose theme={null}
    {
      "object": "list",
      "data": [
        {
          "id": 'meta-llama/Meta-Llama-3.1-8B-Instruct',
          "object": "model",
          "created": 1724480826,
          "owned_by": 'system'
        },
        {
          "id": 'meta-llama/Meta-Llama-3.1-70B-Instruct',
          "object": "model",
          "created": 1724480826,
          "owned_by": 'system'
        },
      ],
      "object": "list"
    }
    ```

    ```Verbose Verbose theme={null}
    {
      "object": "list",
      "data": [
        {
          "id": "meta-llama/Meta-Llama-3.1-8B-Instruct-fast",
          "name": "Meta-Llama-3.1-8B-Instruct (fast)",
          "created": 1750954196,
          "description": "",
          "context_length": 131072,
          "architecture": {
            "modality": "text->text",
            "tokenizer": "Other"
          },
          "quantization": "fp8",
          "pricing": {
            "prompt": "0.00000003",
            "completion": "0.00000009",
            "image": "0",
            "price_per_video_second": "0",
            "request": "0"
          },
          "per_request_limits": {
            "tokens_per_minute": 800000.0,
            "requests_per_minute": 1200.0,
            "burst_ratio": 1.0
          },
          "object": "model",
          "owned_by": "system"
        },
        ...
      ]
    }
    ```
  </CodeGroup>
</Accordion>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).

## **Specific model parameter**

1. [Install jq](https://jqlang.org/download/) if you do not have it.
2. Get the model ID: in the **Models** page, next to the model, click → **Copy model ID**.
3. Copy the name of the required parameter. See the list of available parameters in the **RichModel** schema in the [API reference](https://docs.tokenfactory.nebius.com/api-reference/models/list-models#richmodel).
4. Add the values to the following request:

```bash theme={null}
   curl -s 'https://api.tokenfactory.nebius.com/v1/models?verbose=true' \
     -H "Authorization: Bearer $NEBIUS_API_KEY" \
     -H 'accept: application/json' \
     -X GET | jq '.data[] | select(.id == "<model_ID>") | .<parameter_name>'
```


# Overview
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/overview

Nebius Token Factory offers an OpenAI-compatible API for inference and fine-tuning.

Welcome to the API examples library! Here you’ll find practical, real-world requests you can copy, paste, and modify to get results faster.

<Columns>
  <Card title="Text Generation" icon="text" href="/api-reference/examples/text-generation" />

  <Card title="Vision Capabilities" icon="eye" href="/api-reference/examples/vision-capabilities" />

  <Card title="Text Generation for Code Autocomplete" icon="code" href="/api-reference/examples/text-generation-for-code-autocomplete" />

  <Card title="List of Models" icon="list" href="/api-reference/examples/list-of-models" />

  <Card title="Image Generation" icon="image" href="/api-reference/examples/image-generation" />

  <Card title="Create Embeddings" icon="arrow-right" href="/api-reference/examples/create-embeddings" />

  <Card title="Files" icon="file" href="/api-reference/examples/files" />
</Columns>


# Text generation
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/text-generation



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

Here is a sample JSON request body that includes all supported fields:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  completion = client.chat.completions.create(
      model="meta-llama/Meta-Llama-3.1-70B-Instruct",
      messages=[
          {
            "role": "system",
            "content": "You are a chemistry expert. Add jokes about cats to your responses from time to time."
          },
          {
            "role": "user",
            "content": "Hello!"
          },
          {
            "role": "assistant",
            "content": "Hello! How can I assist you with chemistry today? And did you hear about the cat who became a chemist? She had nine lives, but she only needed one formula!"
          }
      ],
      max_tokens=100,
      temperature=1,
      top_p=1,
      top_k=50,
      n=1,
      stream=false,
      stream_options=null,
      stop=null,
      presence_penalty=0,
      frequency_penalty=0,
      logit_bias=null,
      logprobs=false,
      top_logprobs=null,
      user=null,
      extra_body={
          "guided_json": {"type": "object", "properties": {...}}
      },
      response_format={
          "type": "json_object"
      }
  )

  print(completion.to_json())
  ```

  ```bash cURL theme={null}
  curl 'https://api.tokenfactory.nebius.com/v1/chat/completions' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: */*' \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    --data-binary '{
      "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
      "messages": [
        {
          "role": "system",
          "content": "You are a chemistry expert. Add jokes about cats to your responses from time to time."
        },
        {
          "role": "user",
          "content": "Hello!"
        },
        {
          "role": "assistant",
          "content": "Hello! How can I assist you with chemistry today? And did you hear about the cat who became a chemist? She had nine lives, but she only needed one formula!"
        }
      ],
      "max_tokens": 100,
      "temperature": 1,
      "top_p": 1,
      "top_k": 50,
      "n": 1,
      "stream": false,
      "stream_options": null,
      "stop": null,
      "presence_penalty": 0,
      "frequency_penalty": 0,
      "logit_bias": null,
      "logprobs": false,
      "top_logprobs": null,
      "user": null,
      "guided_json": {"type": "object", "properties": {...}}
      "response_format": {"type": "json_object"}
    }'
  ```

  ```javascript JavaScript theme={null}
  const OpenAI = require("openai");

  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1/",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  client.chat.completions.create({
    "max_tokens": 100,
    "temperature": 1,
    "top_p": 1,
    "top_k": 50,
    "n": 1,
    "stream": false,
    "stream_options": null,
    "stop": null,
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "logit_bias": null,
    "logprobs": false,
    "top_logprobs": null,
    "user": null,
    "extra_body": {
      "guided_json": {"type": "object", "properties": {...},}
    },
    "response_format": {
      "type": "json_object"
    },
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "messages": [
      {
        "role": "system",
        "content": "You are a chemistry expert. Add jokes about cats to your responses from time to time."
      },
      {
        "role": "user",
        "content": "Hello!"
      },
      {
        "role": "assistant",
        "content": "Hello! How can I assist you with chemistry today? And did you hear about the cat who became a chemist? She had nine lives, but she only needed one formula!"
      }
    ]
  })
  .then((completion) => console.log(completion));
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "id": "cmpl-*****",
    "choices": [
      {
        "finish_reason": "stop",
        "index": 0,
        "logprobs": null,
        "message": {
          "content": "Hello! It's nice to meet you. Is there something I can help you with, or would you like to chat?",
          "role": "assistant",
          "function_call": null,
          "tool_calls": []
        },
        "stop_reason": null
      }
    ],
    "created": 1721397089,
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "object": "chat.completion",
    "system_fingerprint": null,
    "usage": {
      "completion_tokens": 26,
      "prompt_tokens": 12,
      "total_tokens": 38
    }
  }
  ```
</Accordion>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).


# Text generation for code autocomplete
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/text-generation-for-code-autocomplete



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

Here is a sample JSON request body that includes all supported fields:

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  for chunk in client.completions.create(
          model="meta-llama/Meta-Llama-3.1-70B-Instruct",
          prompt="Say my name",
          max_tokens=7,
          temperature=0,
          stream=True
  ):
      print(chunk.choices[0].text)
  ```

  ```bash cURL theme={null}
  curl 'https://api.tokenfactory.nebius.com/v1/completions' \
    -H "Content-Type: application/json" \
    -H "Authorization: $NEBIUS_API_KEY" \
    -d '{
      "model": "meta-llama/Meta-Llama-3.1-70B-Instruct"
      "prompt": "Say my name",
      "max_tokens": 7,
      "temperature": 0,
      "stream": true
    }'
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1/",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  async function main() {
    const stream = await openai.completions.create({
      model: "meta-llama/Meta-Llama-3.1-70B-Instruct",
      prompt: "Say my name",
      stream: true,
    });

    for await (const chunk of stream) {
      console.log(chunk.choices[0].text);
    }
  }

  main();
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "id": "cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe",
    "object": "text_completion",
    "created": 1690759111,
    "choices": [
      {
        "text": "Heisenberg",
        "index": 0,
        "logprobs": null,
        "finish_reason": null
      }
    ],
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "system_fingerprint": "fp_44709d6aaa"
  }
  ```
</Accordion>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).


# Vision capabilities
Source: https://docs.tokenfactory.nebius.com/api-reference/examples/vision-capabilities



For the following example to work, save your [API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication) to the `NEBIUS_API_KEY` environment variable.

You can pass images in the following ways:

* A URL to the image.
* A base64 encoded image directly in the request.

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  response = client.chat.completions.create(
      model="Qwen/Qwen2-VL-72B-Instruct",
      messages=[
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "What’s in this image?"},
                  {
                      "type": "image_url",
                      "image_url": {
                          "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
                      },
                  },
              ],
          }
      ],
      max_tokens=300,
  )

  print(response.choices[0])
  ```

  ```bash cURL theme={null}
  curl 'https://api.tokenfactory.nebius.com/v1/chat/completions' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: */*' \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    --data-binary '{
      "model": "Qwen/Qwen2-VL-72B-Instruct",
      "messages": [
        {
          "role": "user",
          "content": [
          {
            "type": "text",
            "text": "What’s in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
            }
          }
        ]
        }
      ],
      "max_tokens": 100
    }'
  ```

  ```javascript JavaScript theme={null}
  const OpenAI = require("openai");

  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1/",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  client.chat.completions.create({
    "max_tokens": 100,
    "temperature": 1,
    "top_p": 1,
    "top_k": 50,
    "n": 1,
    "stream": false,
    "stream_options": null,
    "stop": null,
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "logit_bias": null,
    "logprobs": false,
    "top_logprobs": null,
    "user": null,
    "extra_body": {
      "guided_json": {"type": "object", "properties": {...},}
    },
    "response_format": {
      "type": "json_object"
    },
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "messages": [
      {
        "role": "user",
        "content": [
          { type: "text", text: "What’s in this image?" },
          {
            type: "image_url",
            image_url: {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
            },
          },
        ]
      }
    ]
  })
  .then((completion) => console.log(completion));
  ```
</CodeGroup>

For detailed field descriptions, see the [API reference](https://docs.tokenfactory.nebius.com/api-reference/introduction).


# Delete file
Source: https://docs.tokenfactory.nebius.com/api-reference/files/delete-file

https://api.tokenfactory.nebius.com/openapi.json delete /v1/files/{file_id}



# List user files
Source: https://docs.tokenfactory.nebius.com/api-reference/files/list-user-files

https://api.tokenfactory.nebius.com/openapi.json get /v1/files



# Retrieve file
Source: https://docs.tokenfactory.nebius.com/api-reference/files/retrieve-file

https://api.tokenfactory.nebius.com/openapi.json get /v1/files/{file_id}



# Retrieve file content
Source: https://docs.tokenfactory.nebius.com/api-reference/files/retrieve-file-content

https://api.tokenfactory.nebius.com/openapi.json get /v1/files/{file_id}/content



# Returns URL with link to download file content
Source: https://docs.tokenfactory.nebius.com/api-reference/files/returns-url-with-link-to-download-file-content

https://api.tokenfactory.nebius.com/openapi.json get /v1/files/{file_id}/link



# Upload file
Source: https://docs.tokenfactory.nebius.com/api-reference/files/upload-file

https://api.tokenfactory.nebius.com/openapi.json post /v1/files



# Cancel fine-tuning job
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/cancel-fine-tuning-job

https://api.tokenfactory.nebius.com/openapi.json post /v1/fine_tuning/jobs/{job_id}/cancel
Immediately cancel a fine-tuning job.



# Create a fine-tuning job
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/create-a-fine-tuning-job

https://api.tokenfactory.nebius.com/openapi.json post /v1/fine_tuning/jobs
Creates a job that fine-tunes a specified model based on a given dataset.



# Get fine-tuning checkpoint
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/get-fine-tuning-checkpoint

https://api.tokenfactory.nebius.com/openapi.json get /v1/fine_tuning/jobs/{job_id}/checkpoints/{checkpoint_id}
Get details about a specific checkpoint from a fine-tuning job.



# Get fine-tuning job info
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/get-fine-tuning-job-info

https://api.tokenfactory.nebius.com/openapi.json get /v1/fine_tuning/jobs/{job_id}
Get info about a fine-tuning job.



# List fine-tuning checkpoints
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/list-fine-tuning-checkpoints

https://api.tokenfactory.nebius.com/openapi.json get /v1/fine_tuning/jobs/{job_id}/checkpoints
Get training checkpoints for a fine-tuning job.



# List fine-tuning events
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/list-fine-tuning-events

https://api.tokenfactory.nebius.com/openapi.json get /v1/fine_tuning/jobs/{job_id}/events
Get status updates for a fine-tuning job.



# List fine-tuning jobs
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/list-fine-tuning-jobs

https://api.tokenfactory.nebius.com/openapi.json get /v1/fine_tuning/jobs
Lists all fine-tuning jobs.



# List spec-draft trainable models
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/list-spec-draft-trainable-models

https://api.tokenfactory.nebius.com/openapi.json get /v1/fine_tuning/models/spec-draft
Lists Hugging Face models supported for spec-draft training with their billing price bucket.



# List spec-draft trainable models
Source: https://docs.tokenfactory.nebius.com/api-reference/fine-tuning/list-spec-draft-trainable-models-1

https://api.tokenfactory.nebius.com/openapi.json get /fine_tuning/models/spec-draft
Lists Hugging Face models supported for spec-draft training with their billing price bucket.



# Create a response
Source: https://docs.tokenfactory.nebius.com/api-reference/inference/create-a-response

https://api.tokenfactory.nebius.com/openapi.json post /v1/responses
Creates a model response for a given input



# Create chat completion
Source: https://docs.tokenfactory.nebius.com/api-reference/inference/create-chat-completion

https://api.tokenfactory.nebius.com/openapi.json post /v1/chat/completions
Creates a model response for the given chat conversation.



# Create completion
Source: https://docs.tokenfactory.nebius.com/api-reference/inference/create-completion

https://api.tokenfactory.nebius.com/openapi.json post /v1/completions
Creates a model completion for the given input prompt.



# Create embeddings
Source: https://docs.tokenfactory.nebius.com/api-reference/inference/create-embeddings

https://api.tokenfactory.nebius.com/openapi.json post /v1/embeddings
Creates a model response for the given text.



# Generate
Source: https://docs.tokenfactory.nebius.com/api-reference/inference/generate

https://api.tokenfactory.nebius.com/openapi.json post /v1/images/generations



# Rerank documents
Source: https://docs.tokenfactory.nebius.com/api-reference/inference/rerank-documents

https://api.tokenfactory.nebius.com/openapi.json post /v1/rerank
Reranks documents based on their relevance to a query.



# Introduction
Source: https://docs.tokenfactory.nebius.com/api-reference/introduction



<Note>
  Nebius Token Factory offers an [OpenAI-compatible API](https://docs.tokenfactory.nebius.com/api-reference/models/list-models) for inference and fine-tuning.
</Note>

Here are examples of Python, cURL and JavaScript SDK command that makes an API request from your terminal:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY"),
  )

  completion = client.chat.completions.create(
      model="meta-llama/Meta-Llama-3.1-70B-Instruct",
      messages=[
          {
              "role": "user",
              "content": """Hello!"""
          }
      ],
      temperature=0.6
  )

  print(completion.to_json())
  ```

  ```bash cURL theme={null}
  curl 'https://api.tokenfactory.nebius.com/v1/chat/completions' \
    -X 'POST' \
    -H 'Content-Type: application/json' \
    -H 'Accept: */*' \
    -H "Authorization: Bearer $NEBIUS_API_KEY" \
    --data-binary '{"temperature":0.6,"model":"meta-llama/Meta-Llama-3.1-70B-Instruct","messages":[{"role":"user","content":"Hello!"}]}'
  ```

  ```javascript JavaScript theme={null}
  const OpenAI = require("openai");
  const client = new OpenAI({
    baseURL: "https://api.tokenfactory.nebius.com/v1/",
    apiKey: process.env.NEBIUS_API_KEY,
  });

  client.chat.completions.create({
    "temperature": 0.6,
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  })
  .then((completion) => console.log(completion));
  ```
</CodeGroup>

<Accordion title="Response">
  ```
  {
    "choices": [
      {
        "finish_reason": "stop",
        "index": 0,
        "message": {
          "content": "Hello! It's nice to meet you. Is there something I can help you with, or would you like to chat?",
          "role": "assistant"
        }
      }
    ],
    "created": 1717516032,
    "model": "meta-llama/Meta-Llama-3-70B-Instruct-cheap",
    "object": "chat.completion",
    "usage": {
      "completion_tokens": 26,
      "prompt_tokens": 13,
      "total_tokens": 39
    }
  }

  ```
</Accordion>

For more examples, see [Examples of using the Nebius Token Factory API](https://docs.tokenfactory.nebius.com/api-reference/examples/overview).

## Authentication

To authenticate, include your *API key* (e.g., `ABC123...`) in the `Authorization` header, as shown below:

```
Authorization: Bearer ABC123...
```

<Warning>
  Keep your keys private; do not share or expose them in client-side code. If a key is compromised, Nebius Token Factory can automatically revoke it
</Warning>

To get an API key:

1. In Nebius Token Factory, go to the [API keys](https://tokenfactory.nebius.com/project/api-keys) section.
2. Click  **Create API key**.
3. Enter the key name and then click **Create**.
4. Save the displayed API key. You cannot open it later in Nebius Token Factory.

<Tip>
  In the [Nebius Token Factory inference playground](https://tokenfactory.nebius.com/playground), you can view your model setup and chat as code that makes API requests, and use this code in your applications. For more details, see [View code](https://docs.tokenfactory.nebius.com/ai-models-inference/playground#view-code).
</Tip>

<Tip>
  You can use [integrations with third-party instruments](https://docs.tokenfactory.nebius.com/integrations/overview) instead of the API.
</Tip>


# List models
Source: https://docs.tokenfactory.nebius.com/api-reference/models/list-models

https://api.tokenfactory.nebius.com/openapi.json get /v1/models
Lists the currently available models, and provides basic information about each one such as the owner and availability.



# Get current token information
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/auth/get-current-token-information

https://eu-north.nebius.computer/static/api.yaml get /whoami
Returns information about the current authentication token, including
the token UUID, expiration time, and a map of all known permissions
with their granted status.




# Check if a file exists for the current namespace
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/files/check-if-a-file-exists-for-the-current-namespace

https://eu-north.nebius.computer/static/api.yaml head /files/{sha256}
Returns 200 if the file is uploaded by the current namespace, otherwise 404.



# Get file info by SHA256
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/files/get-file-info-by-sha256

https://eu-north.nebius.computer/static/api.yaml get /files/{sha256}
Returns file info (uuid, sha256, created_at, updated_at).



# List uploaded files for the current namespace
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/files/list-uploaded-files-for-the-current-namespace

https://eu-north.nebius.computer/static/api.yaml get /files
Returns a paginated list of uploaded files for the current namespace.



# Upload a file to the server. the body must be a file content.
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/files/upload-a-file-to-the-server-the-body-must-be-a-file-content

https://eu-north.nebius.computer/static/api.yaml post /files
Uploads a file to the server. The body must contain the file content.



# Add a tag to an image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/images/add-a-tag-to-an-image

https://eu-north.nebius.computer/static/api.yaml patch /images/{imageUUID}/tag
Adds a tag to an image. Tags are unique per namespace; if the requested tag is already
assigned to another image, it will be moved to this image.

Assigning a tag that matches a public tag to a public image will freeze that tag
to the current image - subsequent public updates to the tag will not affect it.
To make the public tag track the latest public image again, remove your tag assignment.

When a tag is removed from an image that resides in the public namespace, the API returns HTTP 200 OK.
response body contains the tag that now points to the public image
(i.e., the image that the tag is automatically re‑assigned to).

In other words, un‑tagging a public image does not delete the tag; it simply moves the tag back to the public
image and the caller receives that tag in the successful response.




# Import a container image from a registry
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/images/import-a-container-image-from-a-registry

https://eu-north.nebius.computer/static/api.yaml post /images/import
Imports the OCI image filesystem content of from a specified registry.

Important limitations and behavior:

- Only the image root filesystem (files and directories) is imported. This is like to the output of
  `docker export` and does not preserve layers metadata.
- Most image configuration and manifest data are ignored. Metadata such as `LABEL`,
  `ENTRYPOINT`, `CMD`, `WORKDIR`, `EXPOSE` and other image configuration directives
  will **NOT be imported or applied**.
- `ENV` variables defined in the image **are imported** and automatically applied to the
  instance environment when `shell` is set to `true`. When `shell` is `false`, image
  environment variables are not inherited and must be passed explicitly via the `env` field.
- The result is a flat rootfs snapshot with preserved environment variables.
- If the specified tag already exists in the public images, the imported image will replace it.
  To avoid this, you can tag the existing image with a different tag for use it later.
  You also can use image UUIDs it is not changing for imported and existend image.
- In case the remote image is unchanged and already imported, the operation will complete and the same UUID
  will be returned without re-importing the image.

The request creates an import operation which runs asynchronously.




# List publicly available images
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/images/list-publicly-available-images

https://eu-north.nebius.computer/static/api.yaml get /images
Returns a list of all publicly available container images.




# Remove tags from an image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/images/remove-tags-from-an-image

https://eu-north.nebius.computer/static/api.yaml delete /images/{imageUUID}/tag
Removes a tag (or all tags) from an image.

When `tag` query parameter is provided, only that specific tag is removed.
When omitted, all tags are removed from the image.

If any public image has the same tag, tag will start tracking that public image again.

In all other cases tag will be removed and the image will be accessible only by its UUID.




# Check if a file exists in image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/check-if-a-file-exists-in-image

https://eu-north.nebius.computer/static/api.yaml head /inspect/{image_uuid}/download
Checks if a file exists in the specified image without returning the file content



# Check if a path can be archived from image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/check-if-a-path-can-be-archived-from-image

https://eu-north.nebius.computer/static/api.yaml head /inspect/{image_uuid}/archive
Checks if a file or a directory exists in the specified image without streaming the archive



# Download a file from image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/download-a-file-from-image

https://eu-north.nebius.computer/static/api.yaml get /inspect/{image_uuid}/download
Returns file content



# Download a file or a directory from image as tar archive
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/download-a-file-or-a-directory-from-image-as-tar-archive

https://eu-north.nebius.computer/static/api.yaml get /inspect/{image_uuid}/archive
Streams the specified path inside the image root filesystem as a POSIX PAX
tar archive. A directory becomes the archive root; a regular file becomes
a single-entry archive. The response is chunked; total size is not known
upfront. Served as an attachment, `filename` is the path with `/` replaced
by `_` plus `.tar` (e.g. `/bin/true` -> `bin_true.tar`).




# Find image by tag
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/find-image-by-tag

https://eu-north.nebius.computer/static/api.yaml get /inspect/
Redirects to the image inspection endpoint for the specified tag



# Inspect an image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/inspect-an-image

https://eu-north.nebius.computer/static/api.yaml get /inspect/{image_uuid}/
Returns image metadata



# List files in image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/list-files-in-image

https://eu-north.nebius.computer/static/api.yaml get /inspect/{image_uuid}/list
Returns files list



# Redirect to /inspect/
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/redirect-to-inspect

https://eu-north.nebius.computer/static/api.yaml get /inspect
Redirects to /inspect/ with a trailing slash



# Redirect to /inspect/{imageUUID}/
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/redirect-to-inspect-

https://eu-north.nebius.computer/static/api.yaml get /inspect/{imageUUID}
Redirects to /inspect/{imageUUID}/ with a trailing slash



# Search file contents in image
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/search-file-contents-in-image

https://eu-north.nebius.computer/static/api.yaml get /inspect/{image_uuid}/grep
Regex content search inside the image's root filesystem, powered by ripgrep.

Symlinks are never followed during traversal, hidden files are searched,
`.gitignore`-style files inside the image are ignored, and binary files
(containing a NUL byte) are skipped. Rust regex syntax, linear-time matching.

Results are a flat, file-ordered list of lines. `before`/`after` request extra
`type: context` lines around each `type: match` line, mirroring ripgrep's
--json message type field.

`path` may be repeated to search multiple roots in one call, the same way
`pattern`/`glob` already can; results are concatenated in the given order
and share the `max_total` budget across all of them.




# Spawn a new container instance
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/instances/spawn-a-new-container-instance

https://eu-north.nebius.computer/static/api.yaml post /instances
Creates and runs a new execution instance with the specified configuration. 
Requires a valid `Authorization` header.

Common request body rules:

  * The request body must contain at least `command` and `image` fields all other fields can be omitted.
  * If the `command` field is a shell expression, you must set `shell` field to `true`.
  * For specifying the shell binary, you can use `env` field to set `SHELL` variable.
  * When `shell` is `true`, environment variables defined in the image (via `ENV` directives) are
    automatically inherited. When `shell` is `false`, image environment variables are not inherited
    and must be passed explicitly via the `env` field.




# Kill one subprocess
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operation/kill-one-subprocess

https://eu-north.nebius.computer/static/api.yaml delete /operations/{operationId}/subprocesses/{spid}
Sends a signal to the process group of `spid` inside the
running instance.  Without the `signal` parameter the group
gets SIGKILL.  Termination is observable, not returned: the
`exit` event lands in the event log and
`GET /operations/{operationId}/subprocesses/{spid}` reports
the terminal `state` (`signal` set, `exit_code` -1 when killed).

Killing `spid=1` (the main process) effectively ends the
operation, like letting the command fail.




# Result of one subprocess, reconstructed from its events
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operation/result-of-one-subprocess-reconstructed-from-its-events

https://eu-north.nebius.computer/static/api.yaml get /operations/{operationId}/subprocesses/{spid}
Returns an `InstanceResult` for `spid` — the same shape as the
parent operation's `metadata.result` — folded from the
subprocess's event log (spawn / stdout / stderr / exit).
Works for running and terminal operations alike.  While the
process is still running, `state.exit_code` and `state.signal`
are `-1` (unknown) and `resources` holds sentinel defaults;
once the exit event lands they carry the real values.

`stdout` / `stderr` are consolidated and capped at the spec's
`truncate_output_at`.  The raw event stream stays available at
`GET /operations/{operationId}/events?spid={spid}`.




# Spawn an additional subprocess inside a running instance
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operation/spawn-an-additional-subprocess-inside-a-running-instance

https://eu-north.nebius.computer/static/api.yaml post /operations/{operationId}/subprocesses
Starts a new process inside the VM that already hosts the named
operation.  Distinct from `POST /instances`, which spins up a
VM: this endpoint requires a running operation (EXECUTING or
ASSIGNED) and reuses the existing VM.

The body is an `ExecSpec` — process-execution fields only.
VM-level concerns (`image`, `hostname`, `resources_limits`,
`files`, `timeout`, `disposable`, `preserve_env`) are not
accepted here; they were set when the parent operation was
created.

The required permission follows the parent instance:
`SPAWN_DISPOSABLE` when it was spawned with `disposable=true`,
`SPAWN` otherwise.

On success the worker assigns a fresh `spid` (≥2; `spid=1` is
the main process spawned from `metadata`) and the response
carries it in the body plus a `Location` header pointing at
`GET /operations/{operationId}/subprocesses/{spid}` — the
subprocess result reconstructed from its events.




# Write to a subprocess's stdin and/or close it
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operation/write-to-a-subprocesss-stdin-andor-close-it

https://eu-north.nebius.computer/static/api.yaml post /operations/{operationId}/subprocesses/{spid}/stdin
Writes a chunk to the stdin of a live process inside the
running instance — `spid=1` targets the main process, `≥2` the
exec'd children.  Requires the process to have been started
with `stdin.close=false`; otherwise its pipe is already at EOF
and the call returns 409.

`close=true` (the default) signals EOF after writing `value`;
an empty `value` with `close=true` just closes the pipe.  A
client that serializes its own requests gets ordered writes;
concurrent requests to the same spid are safe but their order
is unspecified.

A 504 means the guest write timed out mid-call — the chunk may
or may not have been delivered (e.g. the process stopped
reading and the pipe is full), so blind retries can duplicate
data.




# Cancel an operation
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operations/cancel-an-operation

https://eu-north.nebius.computer/static/api.yaml delete /operations/{operationId}
Cancels an operation



# Get an operation status
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operations/get-an-operation-status

https://eu-north.nebius.computer/static/api.yaml get /operations/{operationId}
Returns the status of an operation.

For an EXECUTING INSTANCE operation, pass `?inflight=1` to
also synthesize the partial `result.stdout` / `result.stderr`
from the live event log.  Off by default — each fetch with
`inflight` triggers an extra subscribe RPC to the guest and
drains its current events.gz, which is wasted work for
clients that only poll for status transitions.




# List operations
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operations/list-operations

https://eu-north.nebius.computer/static/api.yaml get /operations
Returns a list of running and completed operations



# Stream the operation event log via Server-Sent Events
Source: https://docs.tokenfactory.nebius.com/api-reference/sandboxes/operations/stream-the-operation-event-log-via-server-sent-events

https://eu-north.nebius.computer/static/api.yaml get /operations/{operationId}/events
Always returns `text/event-stream` (SSE) on success.  The body
is a sequence of three kinds of lines (per RFC W3C SSE), each
terminated by `\n\n`:

### Frame shapes

**Normal event frame** — one `OperationEvent` JSON object in
`data:`, dispatchable via `event:`:
```
id: <integer event.id>
event: <OperationEventType, e.g. stdout|stderr|spawn|exit>
data: {"id": N, "ts": "...", "spid": ..., "type": "...", "data": {...}}
```
`event:` always matches `data.type`.  See `OperationEvent` and
`OperationEventType` for the per-type payload shape.  Native
`EventSource` dispatches each frame to the matching
`addEventListener("<type>", ...)` handler.

**Server-side error frame** — surfaces handler exceptions to
the connected client without tearing the TCP connection down
mid-stream.  Sent right before the server closes the response:
```
: stream ended with error, retry since last event id

event: sse_error
data: <one-line exception message>
```
The leading SSE comment line lets pure-EventSource clients see
the intent ("retry from Last-Event-Id"); the `sse_error` frame
carries the error text for logging.  Clients should treat this
as a non-clean close and reconnect with the standard SSE
`Last-Event-Id` semantics (see Resuming).

**Keepalive comment** — periodic `: keepalive\n\n` lines
emitted while the stream is idle.  They keep upstream
`proxy_read_timeout` / TCP idle timers fresh and have no
application meaning.  Spec-compliant; EventSource and any SSE
parser must ignore comment lines (those beginning with `:`).

### `follow` semantics

The `follow` parameter controls only whether the stream stays
open after the last currently-known event:

  * `follow=0` (default) — the server emits everything
    currently available and closes the connection.
  * `follow=1` — same start; if the operation is still
    running the server keeps the connection open and forwards
    new events as they appear.  For terminal operations
    `follow=1` is a no-op: there's nothing more to subscribe
    to, so the connection closes after the last event just
    like `follow=0`.

Optional filters:

  * `?spid=N` — only events whose `spid` (Spawned Process ID,
    the routing identity in `OperationEvent`) matches.
  * `?since=N` — only events with `id > N`.

`follow=1` requires `SPAWN` or `SPAWN_DISPOSABLE` on top of
the baseline `LIST` — a long-lived subscription reserves
per-operation server state.  `follow=0` is read-only and
stays under `LIST`.

### Resuming after a drop

Every normal frame carries `id:` — the canonical event id.
On reconnect send the last successfully received id in the
standard `Last-Event-Id` request header (or `?since=N` on
manual GETs); the server resumes from that point.

### Error handling

| Status | Meaning                                          | Client action                                |
|--------|--------------------------------------------------|----------------------------------------------|
| 200    | Stream open                                      | Read frames; reconnect with Last-Event-Id if the stream closes before reaching a terminal event |
| 400    | Malformed query/header (non-integer param)       | Fix request                                  |
| 401    | Missing/invalid auth                             | Refresh credentials                          |
| 403    | Auth lacks LIST (or SPAWN for `follow=1`)        | Use a token with the right scope             |
| 404    | Operation not in this namespace                  | Wrong UUID                                   |
| 410    | Stream is over but the terminal artifact isn't ready yet | Retry after `Retry-After`                    |
| 425    | Not yet ready (operation is still being prepared)| Retry after `Retry-After`                    |
| 502    | Upstream returned an error opening the stream    | Retry; if persistent, escalate               |
| 504    | Upstream took too long to respond                | Retry                                        |

A `200` followed by an `event: sse_error` frame and immediate
close is the in-band equivalent of "the stream broke after we
already committed to a 200" — handle it the same way as 410:
wait briefly, reconnect with `Last-Event-Id`.

See `OperationEvent` for the per-event shape.




# Nebius Token Factory Cookbook
Source: https://docs.tokenfactory.nebius.com/cookbook/overview

Examples and recipes to use with Token Factory

## Repository

The GitHub repository can found here: [https://github.com/nebius/token-factory-cookbook](https://github.com/nebius/token-factory-cookbook)

```shellscript theme={null}
git  clone   https://github.com/nebius/token-factory-cookbook
```

## APIs and Models

<Columns>
  <Card title="Model cards" icon="gift" href="https://github.com/nebius/token-factory-cookbook/tree/main/models">
    GPT-OSS, Qwen3 and more
  </Card>

  <Card title="APIs" icon="chart-network" href="https://github.com/nebius/token-factory-cookbook/tree/main/api">
    openAI, LiteLLM, hugging face, aisuite
  </Card>
</Columns>

## Agents

<Columns>
  <Card title="Starter Agents" icon="user-robot" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#agents-by-functionality" />

  <Card title="Advanced Agents" icon="user-robot" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#agents-by-functionality" />

  <Card title="MCP Agents" icon="user-robot" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#agents-by-functionality" />
</Columns>

### Agents by framework

<Columns>
  <Card title="Agno" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#agno" />

  <Card title="Camel AI" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#camel-ai" />

  <Card title="Crew AI" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#crewai" />

  <Card title="Google ADK" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#google-adk-agent-development-kit" />

  <Card title="Llama-Index" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#llama-index" />

  <Card title="Pydantic" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#pydantic-ai" />

  <Card title="Strands" href="https://github.com/nebius/token-factory-cookbook/tree/main/agents#strands-agent" />
</Columns>

[See all agent examples](https://github.com/nebius/token-factory-cookbook/blob/main/agents/README.md)

## RAG (Retrieval-augmented generation)

<Columns>
  <Card title="Chat with Documents" icon="file-pdf" href="https://github.com/nebius/token-factory-cookbook/tree/main/rag/chat-with-pdf">
    Ask questions about PDF documents
  </Card>

  <Card title="RAG pipeline" icon="road" href="https://github.com/nebius/token-factory-cookbook/tree/main/rag/rag-milvus-1">
    End to end RAG pipeline using vector databases
  </Card>

  <Card title="Content generation" icon="file-pen" href="https://github.com/nebius/token-factory-cookbook/tree/main/rag/content-gen-pipeline-qdrant">
    Create social posts and demo apps
  </Card>
</Columns>

[All RAG examples](https://github.com/nebius/token-factory-cookbook/tree/main/rag)

## Finetuning and Distillation

<Columns>
  <Card title="Distillation" icon="bottle-droplet" href="https://github.com/nebius/token-factory-cookbook/tree/main/distillation/distillation-1">
    Train a smaller model from a teacher
  </Card>

  <Card title="LORA finetuning" icon="sparkles" href="https://github.com/nebius/token-factory-cookbook/blob/main/AddLora.ipynb">
    Efficient training of models
  </Card>
</Columns>

## Fun

<Columns>
  <Card title="Fun images with LORA" icon="image-landscape" href="https://github.com/nebius/token-factory-cookbook/tree/main/lora/lora-1">
    Create fun images using LORA adapters
  </Card>

  <Card title="Pelican challenge" icon="bird" href="https://github.com/nebius/token-factory-cookbook/tree/main/fun/pelican-riding-bicycle">
    A cool vibe benchmark for models
  </Card>
</Columns>

## Community and Apps

<Columns>
  <Card title="Events" icon="calendar-days" href="https://github.com/nebius/token-factory-cookbook/blob/main/community/events.md">
    Hackathons, workshops
  </Card>

  <Card title="Community" icon="people-simple" href="https://github.com/nebius/token-factory-cookbook/blob/main/community/README.md">
    Contributions
  </Card>

  <Card title="Apps" icon="window-restore" href="https://github.com/nebius/token-factory-cookbook/blob/main/apps/README.md">
    Apps gallery
  </Card>
</Columns>


# Import Chat Completions
Source: https://docs.tokenfactory.nebius.com/data-lab/chat-completions



Data Lab allows you to import historical **chat completion logs** into structured datasets for analysis and reuse.

### Source of chat completions

Chat completions may come from:

* API requests to Nebius Token Factory
* Playground interactions

Each completion may include:

* Input messages (system, user, assistant, tool)
* Model outputs
* Metadata (model name, timestamps, token usage, errors, etc.)

### Zero Data Retention (ZDR) behavior

Data import is subject to **Zero Data Retention** settings:

* When ZDR is **enabled**, chat completion logs are not stored.
* When ZDR is **disabled**, chat completion logs are collected and available for import.
* If ZDR was enabled during part of the selected time range, only the periods with ZDR disabled will be imported.

<Note>
  Importing a time range where ZDR was fully enabled will result in an empty import.
</Note>

### Import workflow

1. Click **Import completions**
2. Specify the time range, model, and a name for the import
3. Click **Start import** to initiate the process
4. Imported completions appear as a new dataset in Datasets tab inside Data Lab

Imported datasets can then be:

* Filtered and transformed by sql
* Downloaded
* Used for batch inference or fine-tuning

### Typical use cases

* Reviewing real production prompts and responses
* Debugging incorrect or unexpected model behavior
* Building evaluation datasets from real usage
* Preparing training data without manual logging


# Data Processing
Source: https://docs.tokenfactory.nebius.com/data-lab/data-processing



Data Lab works with several types of data, such as inference logs (chat completions), uploaded datasets, batch inference outputs, and fine-tuning results. To ensure full transparency, this section explains how your data is processed, your level of control, and where processing takes place.

### **How We Handle Your Data**

For all data you submit or generate through Data Lab, including:

* Inference logs - inputs and outputs (unless you enable Zero Data Retention)
* Uploaded datasets
* Filtered datasets
* Batch inference outputs
* Fine-tuning results

Nebius Token Factory acts as a **Data Processor** under the terms of our [Data Processing Agreement (DPA)](https://docs.tokenfactory.nebius.com/legal/dpa).

### **Processing Location**

All Data Lab processing activities, including handling of logs, datasets, batch outputs, and training data, are performed exclusively in the EU-North1 (Finland) data center.

### **Future Changes**

If hosting locations change, we commit to notifying you in advance so you can review compliance implications and adjust your workflows if needed.


# Datasets
Source: https://docs.tokenfactory.nebius.com/data-lab/datasets



Datasets in [**Data Lab**](https://tokenfactory.nebius.com/datalab/datasets) provide a reusable data layer for working with model inputs, outputs, training data, and production inference data.

You can upload your own data, connect data from S3-compatible storage, create datasets from inference logs, and reuse existing datasets for [**fine-tuning**](https://docs.tokenfactory.nebius.com/post-training/overview).

## What is a dataset?

A dataset is a structured collection of rows with a defined schema.

Datasets in Data Lab can come from several sources:

* **Uploaded datasets:** data uploaded directly to Data Lab.
* **S3-connected datasets:** data connected from S3-compatible object storage.
* **Imported inference logs:** historical Chat Completions imported from your Token Factory usage.
* **Derived datasets:** datasets created by filtering or transforming another dataset.

Once created, datasets appear in the **Datasets** section of Data Lab and can be inspected, filtered, downloaded, or used for [**fine-tuning**](https://docs.tokenfactory.nebius.com/post-training/overview).

## Creating a dataset

### Upload a dataset

You can upload structured data directly from your computer.

To upload a dataset:

1. Open **Data Lab → Datasets**.
2. Click **Add dataset**.
3. Select the file you want to upload.
4. Specify the dataset name.
5. Start the upload.

For large datasets, Data Lab uses multipart upload so the file can be transferred in multiple parts instead of requiring a single large request (better to use API).

The dataset becomes available after the upload has been processed successfully.

### Connect a dataset from S3

You can also work with data stored in **S3-compatible object storage**.

This is useful when your datasets are already stored externally or are too large to move between systems as part of every workflow.

Data Lab works with the dataset and its metadata without creating an additional raw-data copy of the source S3 object.

This allows you to:

* keep your existing storage architecture;
* avoid unnecessary data duplication;
* inspect and process datasets through Data Lab;
* use the same data for [**fine-tuning**](https://docs.tokenfactory.nebius.com/post-training/overview).

### Create a dataset from inference logs

Data Lab can convert historical Chat Completions into a dataset.

You can select a time range and model and create a structured dataset containing available request and response information.

Imported data may include:

* id: string
* choice\_id: integer
* prompt: json
* completion: json
* dialogue: json
* started: string
* completed: string
* raw\_prompt: json
* raw\_completion: json
* completion\_tokens: integer
* prompt\_tokens: integer
* ai\_project\_id: string
* model\_flavor\_id: string
* tenant\_user\_account\_id: string
* error\_string: string

If **Zero Data Retention (ZDR)** was enabled when requests were made, those inference logs are not available for import.

## Supported formats

Data Lab currently supports the following dataset formats:

| Format                | Direct upload | S3 connection |
| :-------------------- | :------------ | :------------ |
| JSON Lines (`.jsonl`) | Supported     | Supported     |
| Parquet (`.parquet`)  | Not supported | Supported     |

### JSON Lines

JSON Lines (`JSONL`) is supported both for **direct uploads** and for datasets connected from **S3-compatible storage**.

Each line in a JSONL file must contain a valid JSON object.

Example:

```text theme={null}
{"prompt":"Capital of Australia","completion":"Canberra"}
{"prompt":"Capital of Serbia","completion":"Belgrade"}
```

JSONL is well suited for model-related datasets because it can represent both simple records and nested structures such as conversation messages.

### Parquet

Parquet datasets are supported when connected from **S3-compatible storage**.

Direct upload of Parquet files is currently not supported.

Parquet is recommended for large structured datasets already stored in object storage, particularly when efficient storage and analytical processing are important.


# Fine-tuning
Source: https://docs.tokenfactory.nebius.com/data-lab/fine-tuning



[**Data Lab**](https://tokenfactory.nebius.com/datalab) offers tools for preparing and managing datasets for fine-tuning workflows. For more information on fine-tuning, see the [Post-training documentation](https://docs.tokenfactory.nebius.com/post-training/overview).

### Dataset preparation

You can create fine-tuning datasets by:

* Importing and filtering inference logs (chat completions)
* Uploading and filtering structured datasets

Prepared datasets are stored in Data Lab and can be reused across fine-tuning jobs.

### Reproducibility

By keeping datasets versioned and centralized, Data Lab enables:

* Consistent training inputs across experiments
* Easier comparison of fine-tuning results
* Safer iteration without accidental data changes

### Data location and compliance

* Fine-tuning jobs run in **EU or US data centers**, for more information, see our [Legal Quick Guide](https://docs.tokenfactory.nebius.com/legal/legal-quick-guide#4-data-location:-where-your-data-is-processed) (Data Location part)
* All datasets are stored centrally in the eu-north1 (Finland) data center.

This design balances compliance requirements with operational simplicity.

### Typical use cases

* **Adapting models** to internal domain-specific data
* **Improving response quality** for specific tasks
* Training student models for **distillation pipelines**


# Overview
Source: https://docs.tokenfactory.nebius.com/data-lab/overview



[**Data Lab**](https://tokenfactory.nebius.com/datalab) is the unified workspace inside Nebius Token Factory for working with inference logs (chat completions) and datasets.

It centralizes everything related to **inference logs, dataset preparation, batch inference outputs and fine-tuning**, providing a consistent, clean, and reusable data layer for all model-development workflows.

Data Lab reduces reliance on manual scripts and custom pipelines by bringing your data into a single, unified workflow:

* A single place to **view, filter, and export inference logs (chat completions).**
* A unified interface for **preparing datasets via SQL queries.**
* Reusable datasets for **batch inference and fine-tuning.**

### What lives inside Data Lab

Data Lab stores and manages several types of data:

* **Inference Logs:** automatically collected chat completions generated via API or Playground (unless Zero Data Retention is enabled).
* **Filtered Datasets:** datasets created from inference logs using sql queries.
* **Uploaded Datasets:** user-provided datasets uploaded manually.
* **Batch Inference Outputs:** results generated by batch inference jobs.
* **Fine-tuning Outputs:** artifacts produced by fine-tuning jobs, including model checkpoints and the resulting fine-tuned model.

<Columns>
  <Card title="Import Chat Completions" icon="download" href="/data-lab/chat-completions">
    Data Lab allows you to import historical chat completion logs into structured datasets for analysis and reuse
  </Card>

  <Card title="Fine-tuning" icon="layer-group" href="/data-lab/fine-tuning">
    Fine-tuning workflows support preparing, validating, and managing training datasets through Data Lab interface
  </Card>

  <Card title="Data Processing" icon="folder" href="/data-lab/data-processing">
    This section explains how your data is processed, where it is processed, and what level of control you have
  </Card>

  <Card title="Datasets" icon="folder-upload" href="/data-lab/datasets">
    You can upload your own data, connect data from S3-compatible storage, or create datasets from inference logs
  </Card>
</Columns>


# Overview
Source: https://docs.tokenfactory.nebius.com/integrations/overview

Nebius Token Factory third-party integrations for inference

## APIs

In addition to the [playground](https://docs.tokenfactory.nebius.com/ai-models-inference/playground) and the OpenAI-compatible [API](https://docs.tokenfactory.nebius.com/api-reference/introduction), Nebius Token Factory provides integrations with multiple third-party API providers.

<Columns>
  <Card title="AIsuite" icon="chart-network" href="/integrations/api/aisuite" />

  <Card title="Llama-Index" icon="chart-network" href="/integrations/frameworks/llama-index/overview" />

  <Card title="Hugging Face" icon="chart-network" href="/integrations/api/hugging-face" />

  <Card title="LiteLLM" icon="chart-network" href="/integrations/api/litellm" />
</Columns>

## API Routers

<Columns>
  <Card title="Open Router" icon="route" href="/integrations/api-routers/openrouter" />

  <Card title="Hugging Face" icon="route" href="/integrations/api/hugging-face" />

  <Card title="Portkey" icon="route" href="/integrations/api-routers/portkey" />
</Columns>

## AI Application Frameworks

<Columns>
  <Card title="Llama-Index" icon="boxes-stacked" href="/integrations/frameworks/llama-index/overview" />

  <Card title="Langchain" icon="boxes-stacked" href="/integrations/frameworks/langchain" />
</Columns>

## Agent Frameworks

<Columns>
  <Card title="Agno" icon="robot" href="/integrations/agents/agno" />

  <Card title="Camel AI" icon="robot" href="/integrations/agents/camelai" />

  <Card title="CrewAI" icon="robot" href="/integrations/agents/crewai" />

  <Card title="Google ADK" icon="robot" href="/integrations/agents/google-adk" />

  <Card title="Llama-Index" icon="robot" href="/integrations/agents/llama-index" />

  <Card title="Pydantic" icon="robot" href="/integrations/agents/pydantic" />

  <Card title="Strands" icon="robot" href="/integrations/agents/strands" />
</Columns>

[All agents examples](https://github.com/nebius/token-factory-cookbook/tree/main/agents#readme)

## Agentic Search

<Columns>
  <Card title="Tavily" icon="chart-network" href="/integrations/search/tavily" />
</Columns>

## Coding Assistants

<Columns>
  <Card title="Cline" icon="code" href="/integrations/coding/cline" />

  <Card title="Continue" icon="code" href="/integrations/coding/continue" />

  <Card title="Cursor" icon="code" href="/integrations/coding/cursor" />

  <Card title="Kilo Code" icon="code" href="/integrations/coding/kilo" />

  <Card title="VSCode" icon="code" href="/integrations/coding/vscode" />

  <Card title="Zed" icon="code" href="/integrations/coding/zed" />
</Columns>

## Tools

<Columns>
  <Card title="Linkup" icon="chart-network" href="/integrations/tools/linkup" />
</Columns>

## Developer Tools

<Columns>
  <Card title="Postman" icon="chart-network" href="/integrations/dev-tools/postman" />
</Columns>

## Observability

<Columns>
  <Card title="Helicone" icon="eye" href="/integrations/observability/helicone" />

  <Card title="Keywords AI" icon="eye" href="/integrations/observability/keywords-ai" />
</Columns>


# Data Processing Agreement
Source: https://docs.tokenfactory.nebius.com/legal/dpa



This Data Processing Agreement (**“DPA”**) is entered into by and between Nebius B.V. (**“Nebius”** or the **“Processor”**), and the customer identified under the applicable service agreement (**“Customer”**).  

Nebius and Customer are collectively referred to as the **“Parties”** and individually as a **“Party.”**  \
In consideration of the mutual obligations set forth herein, the Parties agree that the terms and conditions described below shall be incorporated into, and form an integral part to, the agreements previously entered into by the Parties, including the Terms of Service (the [**“Terms of Service”**](https://docs.tokenfactory.nebius.com/legal/terms-of-service)), as accepted by Customer.  

In the event of any conflict between the provisions of this DPA and those of the Terms of Service, the provisions of this DPA shall govern with respect to the processing of personal data. 

## **1. Definitions** 

Terms in this DPA have the same meaning as those in the Terms of Service, unless expressly defined otherwise in this DPA. Capitalized terms not defined herein shall have the meaning assigned to them in the Terms of Service.  

1.1. **“Adequacy Decision”** means a decision adopted by the European Commission pursuant to Article 45 of the General Data Protection Regulation, determining that a third country, a territory or one or more specified sectors within that country ensure an adequate level of protection for personal data, allowing transfers of personal data from the European Economic Area (**“EEA”**) to such country without the need for additional safeguards. 

1.2. **“Applicable Data Protection Laws”** means all data protection and privacy laws and regulations applicable to the respective Party in its role in the processing of personal data under the Terms of Service, which may include, to the extent applicable, European Data Protection Laws. 

1.3. **“Customer Content”** means, if not defined within the Terms of Service, all data processed by Nebius on your behalf in the course of providing the Services. 

1.4. **“Customer Personal Data”** means any 'personal data' or ‘personal information’ contained within Customer Content. 

1.5. **“European Data Protection Laws”** means (a) Regulation 2016/679 (General Data Protection Regulation)(**“EU GDPR”**); (b) the EU GDPR as saved into United Kingdom law by virtue of section 3 of the European Union (Withdrawal) Act 2018 (**“UK GDPR”**); and (c) the Swiss Federal Data Protection Act and its implementing regulations (**“Swiss Data Protection Act”**); in each case as may be amended, superseded or replaced from time to time. 

1.6. **“Security Breach”** means a breach of security leading to an accidental or unlawful destruction, loss, alteration, unauthorized disclosure of, or access to, Customer Personal Data. 

1.7. **“Services”** means the services provided to the Customer by Nebius in accordance with the Terms of Services. 

1.8. **“Standard Contractual Clauses”** or **“SCCs”** means the standard contractual clauses annexed to the European Commission's Implementing Decision 2021/914 of 4 June 2021, as may be amended, superseded or replaced from time to time. 

1.9. **“Sub-processor”** means any other processor engaged by Nebius to process Customer Personal Data. 

1.10. **“UK Addendum”** means the International Data Transfer Addendum issued by the Information Commissioners Office under S.119 (a) of the UK Data Protection Act 2018, as updated or amended from time to time. 

1.11. The terms **“controller”**, **“data subject”**, **“supervisory authority”**, **“processor"**, **"process”**, **“processing”**, **“personal data”**, and **“personal information”** shall have the meanings given to them in Applicable Data Protection Laws.  

## **2. Processing of Personal Data** 

2.1. **Scope and Roles of the Parties.** This DPA applies when Customer Personal Data is processed by Nebius as a processor in its provision of the Services to Customer, who will act as either a controller or processor, as applicable, of Customer Personal Data.  

2.2. **Processing by Nebius.** When processing personal data on behalf of Customer, Nebius will (i) comply with Applicable Data Protection Laws; (ii) process personal data only as necessary to perform its obligations under the Agreement and strictly in accordance with Customer’s documented instructions (as set out in the Agreement and this DPA, or as directed by Customer or its Authorized Users through theServices); and (iii) process personal data only for the purposes authorized by Customer. If Nebius is required to process personal data to comply with applicable law to which it is subject, Nebius will inform Customer of that legal requirement before such processing, unless such law prohibits notice. 

2.3. **Processing by Customer.** Customer (i) will comply with Applicable Data Protection Laws in its processing of personal data and in any Instructions it issues to Nebius; (ii) is responsible for using the Services in a secure manner and for independently determining whether the security measures available through the Services satisfy Customer’s legal and contractual obligations; (iii) represents that it has provided all required notices and obtained (and will obtain and maintain) all necessary consents / authorizationd and rights to process personal data through the Services and to provide Nebius with Instructions; and (iv) will inform Nebius without undue delay if Customer is unable to comply with its responsibilities under Applicable Data Protection Laws or its Instructions would cause non-compliance. 

2.4. **Details of Processing.** The subject matter of Nebius’s processing of personal data is the provision of the Services under the Terms of Services. The duration, nature and purpose of the processing, and the types of personal data and categories of data subjects are set out in Annex 2 to this DPA. 

## **3. Assistance Obligations** 

3.1. **Data Subject Requests.** Customer is responsible for responding to and complying with data subject requests **(“DSR”)**. If Nebius receives a DSR directly and the request identifies Customer or enables Nebiusto identify Customer, Nebius will promptly forward the DSR to Customer. Unless legally required to respond, Nebius will not respond to the data subject except to acknowledge receipt and refer the individual to Customer for a response. 

3.2. **Legal Requests.** If Nebius receives a subpoena, court order, warrant, or other legal demand from law enforcement or any public or judicial authority seeking disclosure of Customer Personal Data, Nebius will first attempt to redirect the requesting authority to seek the information directly from Customer and may provide the authority with Customer’s basic contact information for that purpose. If Nebius is compelled to disclose Customer Personal Data, Nebius will provide Customer with reasonable prior notice of the demand so Customer may seek a protective order or other appropriate remedy, unless Nebius is legally prohibited from giving such notice. In responding to any legally binding demand, Nebius will disclose only the minimum amount of Customer Personal Data necessary to comply with the demand and will challenge requests that Nebius reasonably believes are overbroad, unlawful, or otherwise invalid. 

## **4. Sub-processors** 

4.1. **Authorization.** Customer provides a general written authorization for Nebius to engage Sub-processors to process Customer Personal Data in accordance with this Section. Nebius has entered into a written agreement with each Sub-processor that imposes data protection obligations no less protective than those set forth in this Agreement, including with respect to the protection of Personal Data, to the extent applicable to the nature and scope of the Services the Sub-processor provides. 

4.2. **Current List of Sub-processors.** Nebius maintains a current list of Sub-processors engaged to process personal data, including a description of their processing activities and country of location - available at the following link: [https://docs.tokenfactory.nebius.com/legal/subprocessors](https://docs.tokenfactory.nebius.com/legal/subprocessors)[ ](https://docs.tokenfactory.nebius.com/legal/subprocessors\(the)(**the '"Sub-processor List"**). Customer hereby consents to these Sub processors, their locations and processing activities as it pertains to their personal data.

4.3. **Changes to Sub-processors.** Nebius will provide Customer at least fifteen (15) days’ prior notice of any addition or replacement of a Sub-processor. Customer may object on reasonable data-protection grounds to the engagement of a new Sub-processor by providing written notice within that period. The Parties will discuss the objection in good faith. If no mutually acceptable solution is reached, Customer may terminate the affected Services and receive a pro-rata refund of any prepaid, unused fees, without liability to either Party, without prejudice to fees accrued before suspension or termination. 

## **5. Security and Compliance** 

5.1. **Security Measures.** Nebius implements and maintains appropriate technical and organizational measures to safeguard Personal Data. A summary of these security measures is provided in Annex 3 to this DPA. 

5.2. **Security Breaches and Cooperation with Customer.** Nebius will notify the Customer without undue delay after becoming aware of any Security Breach and will provide all necessary information and reasonable assistance to the Customer. 

5.3. **Data Protection Impact Assessments.** Upon reasonable request, Nebius will provide the Customer with information about the Nebius Services necessary for the Customer to conduct data protection impact assessments and any related consultations with supervisory authorities, as required by Applicable Data Protection Laws, provided that the Customer does not otherwise have access to the relevant information. 

5.4. **Audit Program.** Upon written request and at no additional cost to the Customer, Nebius will provide the Customer and/or its appropriately qualified third-party representative with access to documentation reasonably necessary to demonstrate Nebius’s compliance with its obligations under this DPA. 

5.5. **Audits.** Nebius will allow an independent, suitably qualified auditor appointed by the Customer to conduct inspections to verify Nebius’s compliance with its obligations under this DPA, provided that the Customer gives at least 30 days’ prior notice and does not request such inspections more than once per calendar year. All additional costs and expenses incurred by Nebius in connection with such audits may be charged to the Customer. 

## **6. Transfer of Personal Data**  

6.1. **Data Processing Location.** Nebius processes the Customer’s Personal Data within the region selected by the Customer for the dedicated endpoint. If the Customer does not use a dedicated endpoint, the available Model deployment regions are identified by a corresponding flag.

6.2. **Cross-Border Transfers; SCCs.** To the extent any transfer of Personal Data subject to the GDPR, the UK GDPR, or the Swiss FADP is made to a country lacking an Adequacy Decision, such transfer shall be governed by the Standard Contractual Clauses, which shall be deemed incorporated into and form an integral part of the Agreement in accordance with Annex 2 of this DPA. 

## **7. Return and Deletion of Customer Personal Data** 

Upon termination or expiration of the Services, Nebius will, at the Customer’s choice, delete or return any Customer Personal Data processed on the Customer’s behalf. The sole exception is that Nebius may retain Customer Personal Data, in whole or in part, to the extent required by applicable law.  

## **8. General** 

8.1. **Severability.** If any provision of this DPA is found to be invalid or unenforceable, the remaining provisions will remain in full force and effect. 

8.2. **Limitation of Liability.** The liability of each party and their respective Affiliates arising out of or in connection with this DPA will be subject to the limitations and exclusions set forth in the Terms of Service. 

8.3. **Governing Law and Jurisdiction.** This DPA will be governed by, and construed in accordance with, the laws of the Netherlands and will be subject to the exclusive jurisdiction of the Dutch courts. 

8.4. **Order of Precedence.** In the event of any conflict between this DPA and any data protection provisions in other agreements between the Parties relating to the Services, the terms of this DPA will prevail; provided, however, that if and to the extent the Standard Contractual Clauses conflict with this DPA, the Standard Contractual Clauses will control and take precedence.  

## **ANNEX 1 - Details of the Processing** 

**Annex I(A) - LIST OF PARTIES**

**Data Exporter**

| **Field**                                                | **Details**                                                                                                                       |
| :------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| **Name of the data exporter:**                           | The entity identified as the “Customer” in the Terms of Service and this DPA                                                      |
| **Contact person’s name, position and contact details:** | The address and contact details associated with Customer's Account, or as otherwise specified in this DPA or the Terms of Service |
| **Activities relevant to the data transferred:**         | The activities specified in Annex 1(B)below                                                                                       |
| **Signature and date:**                                  | As set out in the Customer’s Account                                                                                              |
| **Role (Controller/Processor):**                         | Controller (for Module 4) or Processor (for Module 2 or 3)                                                                        |

**Data Importer**

| **Field**                                                | **Details**                                                                                     |
| :------------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| **Name of the data importer:**                           | Nebius B.V.                                                                                     |
| **Contact person’s name, position and contact details:** | Marina Benassi, Global Data Protection Officer, [privacy@nebius.com](mailto:privacy@nebius.com) |
| **Activities relevant to the data transferred:**         | The activities specified in Annex 1.B below                                                     |
| **Signature and date:**                                  | As set out in the main agreement                                                                |
| **Role (Controller/Processor):**                         | Processor                                                                                       |

**ANNEX I(B): DESCRIPTION OF THE PROCESSING / TRANSFER:**

| **Field**                                                           | **Details**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Categories of data subjects whose personal data is transferred:** | Customer’s employees, contractors, and any other individuals whose Personal Data is processed by the Customer at its sole discretion in connection with the Services, including individuals added by the Controller to the federated account; as well as other individuals whose Personal Data is contained in Customer Content.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Categories of personal data transferred:**                        | <ul><li>Personal Data processed in the course of the Services as Customer Content</li><li>Voice recordings (for Services related to speech-to-text)</li><li>Personal data necessary for registration, authentication and use of the Services, including: Names and contact details (e.g. email address, telephone number) Job position and company affiliation Technical identifiers (e.g. IP addresses, device IDs, user IDs)</li></ul>                                                                                                                                                                                                                                                                                                                                                    |
| **Sensitive data transferred (if appropriate):**                    | Subject to any applicable restrictions and/or conditions in the Terms of Services and this DPA, Customer may include Sensitive personal data or similarly personal data (as described or defined in Applicable Data Protection Laws, i.e. special categories of personal data) in Customer Personal Data, the extent of which is determined and controlled by Customer in its sole discretion, and which may include, but is not limited to Customer Personal Data revealing racial or ethnic origin, political opinions, religious or philosophical beliefs, or trade union membership, genetic data, biometric data processed for the purposes of uniquely identifying a natural person, data concerning health and/or data concerning a natural person’s sex life or sexual orientation. |
| **Frequency of the transfer:**                                      | Continuous basis depending on the use of the Services by Customer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Nature, subject matter and duration of the processing:**          | **Nature:** Nebius provides the Services, as further described in the Terms of Service. **Subject Matter:** Customer Personal Data. **Duration:** The duration of the processing will be for the term of the Terms of Service.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Purpose(s) of the data transfer and further processing:**         | <ul><li>Performing the Services in accordance with the Terms of Service and this DPA, including processing Customer requests and providing customer support;</li><li>Registering and managing federated accounts to enable the Controller to add employees and representatives to the Services;</li><li>Engaging in service-related communications, such as notifications, updates, and responses to inquiries necessary for the delivery and maintenance of the Services;</li><li>Acting on the Customer’s written instructions in line with the Terms of Service;</li><li>Complying with applicable laws, regulations, and the provisions of this DPA.</li></ul>                                                                                                                          |
| **Sub-processor transfers:**                                        | In relation to transfers to Sub-processors, the subject matter and nature of the processing are specified in the list of Sub-processors (accessible at the link - [https://docs.tokenfactory.nebius.com/legal/subprocessors](https://docs.tokenfactory.nebius.com/legal/subprocessors). The duration of the processing by Sub-processors will be the same as the duration of the Terms of Service, unless otherwise specified in the Terms of Service or this DPA.                                                                                                                                                                                                                                                                                                                          |

**ANNEX 1(C): COMPETENT SUPERVISORY AUTHORITY:**\
Autoriteit Persoonsgegevens (Dutch Data Protection Authority)

## **ANNEX 2 - Standard Contractual Clauses** 

**A. EEA Cross Border Transfers** 

1. The Parties hereby agree to the Standard Contractual Clauses as outlined in the Annex of the European Commission Implementing Decision (EU) 2021/914 of June 4, 2021. 
2. Module Two (controller to processor) of the SCC shall apply where Customer is a controller of the personal data and Nebius acts as a processor. 
3. Module Three (processor to processor) of the SCC shall apply where Customer is a processor of the personal data and Nebius acts as a Sub-processor. 
4. Module Four (processor to controller) of the SCC shall apply where Nebius, acting as a Processor established in the EEA, transfers Personal Data to the Customer acting as a Controller located outside the EEA. 
5. Clause 7 of the SCC (Docking Clause) shall not apply. 
6. For the purposes of Clause 9 of the SCC (concerning Module Three transfers), the Parties choose the option 2 “General Written Authorisation” in Clause 9 of the SCC shall apply, and specify that the processor shall inform in writing the controller of any intended changes of that list through the addition or replacement of Sub-processors at least **fifteen (15) days** in advance, thereby giving the controller sufficient time to be able to object to such changes prior to the engagement of the concerned Sub-processor(s). The Parties also agree that the relevant agreed list of Sub-processors is provided in Annex 1 to this DPA and may be amended from time to time as agreed in this clause.
7. For the purposes of Clause 11 of the SCC, the optional language will not apply. 
8. For the purpose of Clause 17 of the SCC, option 1 shall apply, and the Parties agree that the SCC shall be governed by the laws of the Netherlands. 
9. For the purpose of Clause 18(b), disputes shall be resolved before the courts of the Netherlands. 
10. Annex I.A of the SCC shall be completed as indicated in Annex 1. 
11. Annex I.B of the Standard Contractual Clauses shall be completed as described in Annex I of this DPA. 
12. The period for which the personal data will be retained is for the duration of the Agreement, unless agreed otherwise in the Agreement and/or the DPA. 
13. In relation to transfers to Sub-processors, the subject matter, nature, and duration of the processing is set forth in Annex 1 of this DPA. 
14. Annex I.C of the SCC shall be completed as follows: The competent supervisory authority in accordance with Clause 13 is the supervisory authority in the Member State stipulated in Section 8 above. 
15. Annex 3 of this DPA serves as Annex II of the SCC. 
16. The Parties agree that other clauses and additional safeguards added by this DPA to the SCC do not directly or indirectly contradict the SCC or detract from the fundamental rights or freedoms of data subjects. 
17. To the extent there is any conflict between the Standard Contractual Clauses and any other terms in this DPA or the Terms of Service, the provisions of the Standard Contractual Clauses will prevail. 

**B. UK Cross Border Transfers** 

In relation to transfers of Customer Personal Data protected by the UK GDPR, the SCCs as implemented under section A above shall apply with the following modifications: 

1. The SCCs shall be modified and interpreted in accordance with Part 2 of the [<u>UK Addendum</u>](https://ico.org.uk/media2/migrated/4019539/international-data-transfer-addendum.pdf) (**“UK Addendum”**), which shall be deemed incorporated into and form an integral part of the DPA. 
2. Tables 1, 2 and 3 in Part 1 of the UK Addendum shall be deemed completed with the information set out in Annex 1, Annex 2 and Annex 3 to the DPA, and Table 4 in Part 1 of the UK Addendum shall be deemed completed by selecting "neither party". 
3. Any conflict between the terms of the SCCs and the UK Addendum will be resolved in accordance with Section 10 and Section 11 of the UK Addendum.  

**C. Swiss Cross Border Transfers** 

In relation to transfers of Customer Personal Data protected by the Swiss Data Protection Act, the SCCs as implemented under section A above will apply with the following modifications: 

1. References to “Regulation (EU) 2016/679” (or GDPR) and specific articles therein shall be interpreted as references to the Swiss Data Protection Act and the equivalent articles or sections therein. 
2. References to “EU”, “Union”, “Member State” and “Member State law” shall be replaced with references to “Switzerland” and/or “Swiss law” (as applicable). 
3. References to the “competent supervisory authority” and “competent courts” shall be replaced with references to the “Swiss Federal Data Protection Information Commissioner” and “applicable courts of Switzerland”). 
4. The SCCs shall be governed by the laws of Switzerland. 
5. Disputes shall be resolved before the competent Swiss courts. 

## **ANNEX 3 - Security and Organizational Measures** 

**A. TECHNICAL AND ORGANISATIONAL MEASURES** 

The below provide a description of the technical and organizational measures, which shall be implemented by the Processor (including any relevant certifications) to ensure an appropriate level of security, taking into account the nature, scope, context and purpose of the processing, and the risks for the rights and freedoms of natural persons.  

The Processor shall guarantee to have/be:  

* the ability and technical capacity to ensure the ongoing security, confidentiality, integrity, availability and resilience of processing systems, networks and services. Processor shall maintain network and physical security policies, procedures, and systems and shall perform network security and activities consistent with best practices in Processor’s industry but that, at a minimum, include but are not limited to: network firewall provisioning, intrusion detection, and regular (but in no event less frequently than annually) vulnerability assessments. In no event shall the foregoing as applied to the personal data of the Controller be any less stringent and protective than those applied by Processor to the protection of its own data and systems of a like or similar nature;  
* the ability and technical capacity to restore the availability and access to the personal data in a timely manner in the event of a physical or technical incident;  
* an adequate process for regularly monitoring, testing, assessing and evaluating the effectiveness of technical and organizational measures for ensuring the security of the processing;  
* adequate and current controls and preventive measures in place against access of unauthorized persons to data processing systems (physical access control), concretely the following measures are implemented with respect to Access Management:  

(i) Need-to-Know basis, Least Privilege, Segregation of Duties (SoD);  

(ii) Approval for each access request must be obtained through a verifiable process to confirm the necessity. Information systems must leverage a robust framework consisting of these processes: Identification, Authentication, Authorization, Accounting (logging);  

* proper and accurate controls in place for keeping personal data logically separate from data processed on behalf of any third party and / or for other purposes as well as proper controls regarding sharing of personal data within your organization and with third parties;  
* applying a level of encryption (at rest and in transit) and pseudonymisation of the personal data, appropriate to the risks and personal data processed;  
* ensuring that in the course of processing activities and after storage, personal data cannot be read, copied, modified or deleted without authorization (data access control);  
* envisaging and applying the necessary measures to ensure that the personal data cannot be read, copied, modified or deleted without authorization during electronic transmission, transport or storage, and that the target entities for any transfer of the personal data by means of data transmission facilities can be established and verified (data transfer control);  
* ensuring the establishment of logging and the deployment of an audit trail to document whether and by whom the personal data have been entered into, modified in, or removed from data processing systems (entry control);  
* maintaining and enforcing an information security policy and security incident management and continuity plans, consisting of, among others, the analysis performed in this respect and the risk management of personal data, a description of various responsibilities and organizational rules, description of how security incidents are managed, the measure that were introduced to keep the security system up-to-date after installation;  
* ensuring that information security is led by trained experts with the necessary competences. Moreover, ensuring that the staff is trained and obliged to confidentiality and aware and trained in data protection;  
* ensuring physical environment security, for instance by means of security and surveillance regarding building, premises, and installations where carriers of personal data and computer systems processing the data are positioned, as well as prevention, detection, and operating procedure in the case of fire, intrusion, and water damage;  
* ensuring that asset management process, policy, and procedures are in place (asset inventory is in place with annual reviews);  
* ensuring that human resources processes, policies, and procedures are in place (employee background checks prior to hiring where applicable, account disabling upon termination, annual security awareness trainings, etc.);  
* ensuring that Workload Protection is in place (as additional operational controls);  
* ensuring effective change management process, policy, and procedures are in place (changes are reviewed, tested and approved before deployed to production);  
* maintaining complete and up-to-date documentation proportionate to the risk profile of the processing operations, including, but no limited to, technical documentation of implemented security measures and other information necessary to demonstrate compliance with the requirements of this Annex; and  
* ensuring that the personal data is processed solely in accordance with the relevant controller’s instructions (control of instructions).  

**Security Breach Notification:** In the event of a personal data breach or breach of any of Processor’s security obligations, Processor shall notify the Controller of such an event without undue delay of discovery by telephone and e-mail at the following phone number and email address:  

E-mail: [privacy@nebius.com](mailto:privacy@nebius.com) 

**B. Assistance with Data Subject Requests** 

The below provide a description of the technical and organisational measures, which shall be implemented by Nebius in order to assist the data controller in fulfilling its obligations to respond to data subjects’ requests for the exercise of their rights under the Applicable, and the scope and the extent of the assistance required. 

Nebius shall ensure to have/be: 

* the ability to effectively promptly notify the data controller that it has received a request from a data subject to exercise its rights under the Applicable Data Protection Laws concerning the personal data of the data controller; 
* the ability, at its own cost and expense, to co-operate with the data controller as requested to enable the data controller to comply with exercise of rights by a data subject under the Applicable Data Protection Laws concerning the personal data of the data controller, and to comply with any assessment, inquiry, notice or investigation concerning the personal data of the data controller, which includes: 
* providing all data requested by the data controller within a reasonable timescale, which shall always by set by the data controller, but in any case not longer than 3 days, including full details and copies of the complaint, communication or request and any the personal data of the data controller it holds in relation to a data subject; 
* where applicable, providing such assistance as is reasonably requested by the data controller to comply with the relevant request within the timescales prescribed by the Applicable Data Protection Laws; and 
* implementing any additional technical and organisational measures as may be reasonably required by the data controller to allow the data controller to respond effectively to relevant complaints, communications or requests. 
* the ability to assist the data controller in fulfilling the data controller's obligation to respond to a request to exercise the rights of the data subject. In particular, Nebius undertakes to respond to requests for access to data, requests for rectification and erasure of data, requests for restriction of processing and requests to exercise the right to data portability. 

***

Web address: [https://docs.tokenfactory.nebius.com/legal/dpa](https://docs.tokenfactory.nebius.com/legal/terms-of-service)

**Effective date:** As stated above in the Terms of service\
**Last updated:** March 16, 2026

<Expandable title="previous versions of the document">
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/dpa-20250812](https://docs.tokenfactory.nebius.com/legal/archive/dpa-20250812)
  \
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/dpa-20250401](https://docs.tokenfactory.nebius.com/legal/archive/dpa-20250401)
  \
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/dpa-20241220](https://docs.tokenfactory.nebius.com/legal/archive/dpa-20241220)
</Expandable>


# Acceptable use policy (AUP) FluxDev model
Source: https://docs.tokenfactory.nebius.com/legal/flux-dev



**Limitations:**

i. FluxDev Model is not intended or able to provide factual information.

ii. As a statistical model this checkpoint might amplify existing societal biases.

iii. The model may fail to generate output that matches the prompts.

iv. Prompt following is heavily influenced by the prompting-style.

c. **The model and its derivatives may not be used:**

i. for the purpose of exploiting, harming or attempting to exploit or harm minors in any way; including but not limited to the solicitation, creation, acquisition, or dissemination of child exploitative content.

ii. to generate or disseminate verifiably false information and/or content with the purpose of harming others.

iii. to generate or disseminate personal identifiable information that can be used to harm an individual.

iv. to harass, abuse, threaten, stalk, or bully individuals or groups of individuals.

v. to create non-consensual nudity or illegal pornographic content.

vi. for fully automated decision making that adversely impacts an individual's legal rights or otherwise creates or modifies a binding, enforceable obligation.

vii. for generating or facilitating large-scale disinformation campaigns.

***

Web address: [https://docs.tokenfactory.nebius.com/legal/flux-dev](https://docs.tokenfactory.nebius.com/legal/flux-dev)

Publication date: January 20, 2025\
Effective date: January 20, 2025


# HIPAA & BAA Support for Nebius Token Factory
Source: https://docs.tokenfactory.nebius.com/legal/hipaa-guideline



### **Disclaimer** 

This document is for informational purposes only and does not constitute legal advice. Use of Nebius products with Protected Health Information (PHI) or electronic Protected Health Information (ePHI)is subject to a signed Business Associate Agreement (BAA), proper configuration, and customer responsibilities consistent with the Health Insurance Portability and Accountability Act (HIPAA). 

### **Intended Audience** 

This guide is intended for compliance officers, security engineers, and technical leads at healthcare organizations or partners who wish to use Nebius Token Factory in HIPAA-regulated environments. 

### **Definitions** 

Any capitalized terms used but not otherwise defined in this document have the same meaning as in [HIPAA](https://www.hhs.gov/hipaa/for-professionals/index.html).  

### **Overview** 

* HIPAA compliance is a **shared responsibility**: Nebius provides infrastructure, controls, and features designed to support HIPAA, but the customer must configure and use them correctly (as is common in cloud and AI settings). 
* Nebius is prepared to enter into a **Business Associate Agreement (BAA)** to cover HIPAA use, subject to meeting the constraints described here. 
* Only certain Nebius features and API methods are eligible under the BAA; usage outside those scopes is **not covered**. 

### **Covered Products** 

Below is the list of Nebius capabilities that **can** be included under the BAA, when used under specific constraints: 

| **Feature / Method**                                 | **Covered under BAA?** | **Requirements / Notes**            |
| :--------------------------------------------------- | :--------------------- | :---------------------------------- |
| /chat/completions API                                | Yes                    | Must enable **Zero Data Retention** |
| /completions API                                     | Yes                    | Must enable **Zero Data Retention** |
| Fine-tuning / training APIs                          | No                     | Excluded from BAA scope             |
| Batch inference                                      | No                     | Excluded from BAA scope             |
| Embeddings, file upload, storage, dataset management | No                     | Not covered unless explicitly added |

If a capability is not listed above, it is **not considered covered** under the BAA by default. 

### **Customer Responsibilities** 

A customer must determine whether or not they, the customer, are a Covered Entity (or a Business Associate of a Covered Entity) and, if so, whether they require a Business Associate Agreement with Nebius. 

While Nebius can assist in this determination and provide a secure and compliant infrastructure for the storage and processing of PHI/ePHI, the customer bears sole and ultimate responsible for ensuring that the environment and applications that the Customer builds and utilizes alongside or in conjunction with the Nebius Token Factory are properly configured and secured according to HIPAA requirements. This may also be called a “shared security model” or “shared responsibility” as outlined above. 

To operate within HIPAA scope using Nebius, customers must: 

1. **Sign a BAA** \
   Engage Nebius to execute a Business Associate Agreement before transmitting any PHI/ePHI. 
2. **Use only the covered API methods** \
   Restrict your application to /chat/completions and /completions for PHI/ePHI traffic. 
3. **Enable Zero Data Retention** \
   Configure Nebius so that request and response content (including PHI/ePHI) is **not persisted** beyond ephemeral processing. 
4. **Do not include ePHI/PII in metadata, tags or key names** 

Customers must not include electronic Protected Health Information (ePHI), personally identifiable information (PII), or any other confidential data in metadata, tags, or key names 

### **How to Obtain a BAA with Nebius** 

1. **Contact your account manager** and request a HIPAA / BAA evaluation. 
2. **Provide your intended use case**, confirming that you will adhere to the covered methods and zero data retention constraints. 
3. Once reviewed and accepted, Nebius will supply a BAA document for your signature. 
4. After execution, your use of supported endpoints with proper configuration will be eligible to carry PHI/ePHI under the BAA. 

 


# Legal Quick Guide
Source: https://docs.tokenfactory.nebius.com/legal/legal-quick-guide



## 1. Introduction: Our Commitment to Your Privacy

At **Nebius Token Factory**, your trust is our top priority. We are committed to protecting your data, respecting your privacy, and operating in full compliance with applicable laws, including the General Data Protection Regulation (GDPR).

This guide provides clear, plain-language answers to your most common questions about how we handle your data, where it is processed, and the rights and controls you have as a user.

**Please note:** this guide is a summary for your convenience. It does not amend or replace our Terms of Service, Data Processing Agreement (DPA) or Privacy Policy; in case of any inconsistency, those documents prevail.

## 2. Who You Contract With

Your contract for Nebius Token Factory is with **Nebius B.V.**, a company incorporated in the Netherlands. Nebius B.V. also acts as the Data Processor under our DPA, which is governed by the laws of the Netherlands.

Nebius B.V. is a subsidiary of **Nebius Group N.V.**, the publicly listed parent company of the Nebius group (NASDAQ: NBIS). Other Nebius group companies may participate in delivering the service as sub-processors – see Section 6.

## 3. Data Processing: What Happens to Your Data

To provide our service, we handle different types of data. It is important to understand our role in each case:

**3.1. Data Controller:** for your account information (e.g., email address, billing details), we act as the Data Controller: we determine how this data is used for authentication, billing and communication with you.

**3.2. Data Processor:** for the content you submit to our model inference and fine-tuning endpoints via the API or web interface (prompts, datasets, etc.) and the output you receive, we act as the Data Processor under our DPA. You are the Data Controller and remain in full control of this data. The detailed subject matter, duration, categories of data subjects and personal data are set out in Annex 1 of the DPA.

**3.3. Speculative Decoding:** to improve output speed, your inputs (prompts) and the corresponding outputs may be stored and used for Speculative Decoding. You have complete control over this and can switch it off (see Section 4).

* **How Speculative Decoding works and why we need your data:** this feature speeds up inference by introducing a draft model. The draft model generates multiple candidate tokens, and the main model only verifies or corrects them. This reduces the number of expensive forward passes and improves throughput. It is enabled by default for best performance; you can opt out at any time by enabling Zero Data Retention. Enabling Zero Data Retention may impact the level of service provided (e.g., inference speed).

## 4. Your Controls: Data Retention, Opt-Outs & Deletion

**4.1. Zero Data Retention (ZDR)**

For maximum privacy and control, you can enable Zero Data Retention in your account settings.

* **Scope:** ZDR applies at the organization level and covers all projects and endpoints within your organization. Enabling or disabling ZDR is your responsibility as the account owner.
* **What it means:** with ZDR enabled, your inputs (prompts) and outputs (responses) are not stored on our systems after each request is processed – no retained copy exists beyond ephemeral in-flight processing.
* **No training, no Speculative Decoding:** with ZDR enabled, your data is not used for Speculative Decoding and is not used to train, fine-tune or improve any model – whether ours or a third party's.
* **How to enable it:** activate Zero Data Retention on your account profile page.
* **Written confirmation:** if you need written confirmation of your organization's ZDR status (e.g., for a data-protection review), contact our support team or your account manager.

**4.2. Default Behavior**

Unless you enable Zero Data Retention, we keep your inputs and outputs to speed up inference using the Speculative Decoding technique described in Section 3. Your content is not used to train any models in either mode.

**4.3. Return & Deletion at End of Contract**

When you stop using the service, you decide what happens to your data: upon termination or expiration of the services, we will delete or return Customer Personal Data at your choice, unless retention of certain data is required by applicable law (DPA, Section 7).

## 5. Data Location: Where Your Data Is Processed

**5.1. Choice of Location & Full Transparency**

**Real-time processing (inference):** the country flag displayed for each model indicates where your requests are processed in real time, that is, where inference on your inputs and outputs actually takes place. We offer models running in data centers located in the European Union (including Finland and France), Israel, and the United States. For public model endpoints, available processing locations may change from time to time, the current location for each model is always shown in the Nebius Token Factory interface (country flags) and in its documentation, so you can see exactly where your data will be processed before you use a specific model and make an informed, compliant choice.

**Storage after processing:** real-time processing and subsequent storage are distinct. If you have not enabled Zero Data Retention (see Section 4), the inputs and outputs retained for Speculative Decoding are stored in Finland (EU), regardless of where real-time processing takes place. With ZDR enabled, no inputs or outputs are retained.

**5.2. Dedicated Endpoints: Region Commitment**

For dedicated endpoints, the data-center region is fixed as part of the endpoint configuration – and it is a contractual commitment: under Section 6.1 of our DPA, we process your personal data within the region you selected for your dedicated endpoint.

* We do not use multi-region routing, load balancing, or automatic overflow/failover to other regions for dedicated endpoints: inference runs only in the region you chose.
* If your dedicated endpoint is configured in the EU, the inference content and related metadata remain within that region.

**5.3. Fine-Tuning Data Location & Storage**

Fine-tuning workloads have fixed processing locations, and all resulting data is stored centrally in the EU to ensure consistent compliance and governance:

* **Data storage (global policy):** regardless of customer origin (EU, US, or other regions), all fine-tuning datasets, artifacts, and model outputs are stored exclusively in EU data centers.
* **Processing for EU customers:** fine-tuning jobs submitted by EU users are processed in EU data centers, and their data is stored in the EU.
* **Processing for US customers:** fine-tuning jobs submitted by US users are processed in US data centers, but all data is stored in the EU.

Fine-tuning does not offer regional selection options, unlike inference endpoints.

**5.4. Future Changes**

We notify customers in advance of changes that may affect their compliance posture:

* **Terms of Service and DPA changes:** we provide notice of any changes to our Terms of Service, including the DPA. Previous versions of our legal documents remain available in the online archive on the documentation site.
* **Sub-processor changes:** at least fifteen (15) days' prior notice of any addition or replacement of a subprocessor.
* **Model deprecations:** deprecations of models are announced in advance so you can migrate your workloads.

## 6. Sub-Processors

Like every cloud provider, we rely on carefully selected sub-processors – both Nebius group companies and external providers – for parts of the service such as cloud infrastructure, inference capacity, customer support, payments and billing.

* **Current list:** we maintain a public, up-to-date Sub-processor List showing each sub-processor's role and location, together with the list's effective date: [https://docs.tokenfactory.nebius.com/legal/subprocessors](https://docs.tokenfactory.nebius.com/legal/subprocessors) .
* **Safeguards:** each sub-processor is bound by a written agreement imposing data-protection obligations no less protective than those in our DPA.
* **Advance notice of changes:** we will give you at least fifteen (15) days' prior notice before adding or replacing a sub-processor. You may object on reasonable data-protection grounds; if no mutually acceptable solution is found, you may terminate the affected services and receive a pro-rata refund of prepaid, unused fees.

## 7. International Data Transfers

* **Standard Contractual Clauses (SCCs):** where personal data protected by the GDPR, UK GDPR or Swiss FADP is transferred to a country without an adequacy decision, the transfer is governed by the EU Standard Contractual Clauses (Commission Implementing Decision (EU) 2021/914), which are incorporated into our DPA. This also covers administrative, maintenance and support access to data from outside the EEA – for example, by Nebius group entities in the United States, Israel or Serbia listed in the Sub-processor List.
* **United Kingdom and Switzerland:** transfers of UK-protected data are additionally covered by the ICO's International Data Transfer Addendum, and Swiss-protected data by the Swiss adaptations, both set out in Annex 2 of the DPA.
* **EU-US Data Privacy Framework (DPF):** we are certified under the EU-US Data Privacy Framework, which enables compliant transfers of personal data from the EU/EEA to the United States in addition to other available transfer mechanisms. As a DPF-certified organization, we adhere to the DPF Principles and maintain safeguards designed to ensure an appropriate level of protection for EU personal data.

## 8. Compliance & Certifications

**8.1. GDPR Compliance**

We are fully compliant with the General Data Protection Regulation (GDPR). Our practices and policies are built to meet these rigorous requirements for data protection.

**8.2. Data Processing Agreement (DPA)**

We provide a DPA to all our customers. To keep the process simple, the DPA is incorporated directly into our Terms of Service: by signing up and agreeing to the Terms of Service, you are covered by the DPA – no separate signature is needed.

If your procurement or regulatory process requires a countersigned copy of the DPA or additional contractual arrangements, contact your account manager or our support team.

**8.3. Certifications**

We are a certified company holding **ISO 27001**, **ISO 27701** and **SOC 2 Type II** certifications. These internationally recognized standards demonstrate our commitment to information security, privacy, and operational resilience. For details, visit our Trust Center: [https://nebius.com/trust-center](https://nebius.com/trust-center) .

**8.4. Requesting Audit Reports**

Audit reports and certificates (e.g., the SOC 2 Type II report) are available through our Trust Center; certain reports are shared under a non-disclosure agreement. If a third party – such as an external risk assessor – requests reports on your behalf, we will ask for your authorization first.

In addition, under the DPA you may request, in writing and at no cost, documentation reasonably necessary to demonstrate our compliance, and you may commission an audit by an independent, suitably qualified auditor with at least 30 days' notice, once per calendar year.

**8.5. HIPAA Compliance**

We also provide secure services to help customers meet the requirements of the U.S. Health Insurance Portability and Accountability Act (HIPAA). More details: [https://docs.tokenfactory.nebius.com/legal/hipaa-guideline](https://docs.tokenfactory.nebius.com/legal/hipaa-guideline) .

## 9. Security, Audits & Incident Response

* **Security measures:** we implement and maintain appropriate technical and organizational measures, summarized in Annex 3 of the DPA. They include encryption at rest and in transit, access management based on need-to-know, least privilege and segregation of duties, logging and audit trails, physical security of data centers, personnel background checks and confidentiality training, change management, and business-continuity plans.
* **Breach notification:** we will notify you without undue delay after becoming aware of a security breach affecting your personal data and will provide the necessary information and reasonable assistance.

## 10. Sensitive & Regulated Data

* **Special-category personal data (Art. 9 GDPR):** our DPA expressly contemplates that Customer Content may include special categories of personal data – such as health data or biometric data – the extent of which you determine and control (DPA Annex 1(B)). As the Data Controller, you are responsible for ensuring a lawful basis and for any required notices, consents or authorizations before submitting such data.
* **Recommended controls:** for sensitive workloads, we recommend enabling Zero Data Retention and using a dedicated endpoint in your preferred region (see Sections 4 and 5).
* **US healthcare data:** for HIPAA-regulated workloads, see our HIPAA guideline (Section 8.5).

## 11. Ownership & Copyright

You own what you create. We claim no rights to the intellectual property you develop on our platform.

* You retain all ownership rights to your input data and datasets.
* You retain all ownership rights to any fine-tuned and distilled models you create.
* You retain all ownership rights to the content generated by the models from your inputs.
* You acknowledge that your outputs may not be unique, and other users of the service may receive the same or similar outputs.

## 12. Key Documents & Contacts

* **Terms of Service:** [https://docs.tokenfactory.nebius.com/legal/terms-of-service](https://docs.tokenfactory.nebius.com/legal/terms-of-service)
* **Privacy Policy:** [https://docs.tokenfactory.nebius.com/legal/privacy-policy](https://docs.tokenfactory.nebius.com/legal/privacy-policy)
* **Data Processing Agreement:** [https://docs.tokenfactory.nebius.com/legal/dpa](https://docs.tokenfactory.nebius.com/legal/dpa)
* **Sub-processor List:** [https://docs.tokenfactory.nebius.com/legal/subprocessors](https://docs.tokenfactory.nebius.com/legal/subprocessors)  (each version shows its effective date)
* **HIPAA Guideline:** [https://docs.tokenfactory.nebius.com/legal/hipaa-guideline](https://docs.tokenfactory.nebius.com/legal/hipaa-guideline)
* **Trust Center (certifications & reports):** [https://nebius.com/trust-center](https://nebius.com/trust-center)

**Privacy contact:** [privacy@nebius.com](mailto:privacy@nebius.com) (Data Protection Officer). For written confirmations, countersigned documents or contractual addenda, contact your account manager or our support team.

## 13. Frequently Asked Questions (FAQ)

### Data Processing & Location

**Where is my data processed?**

The processing location depends on the specific AI model you choose. We host models in data centers within the European Union, the United States and Israel. You can see the specific location for each model in the Nebius Token Factory interface before you use it.

**Will my dedicated endpoint ever process data in another region?**

No. Under Section 6.1 of our DPA, we process your personal data within the region you selected for the dedicated endpoint. There is no multi-region routing or automatic overflow to other regions.

**How will I be notified about changes in model hosting locations?**

We announce such changes proactively via email to all account owners and through notifications within the Nebius Token Factory platform.

**If my data is processed in the US, how do you ensure it complies with EU regulations like GDPR?**

For any transfers to countries without an EU adequacy decision, we rely on legally established transfer mechanisms – in particular the Standard Contractual Clauses incorporated into our DPA – and we are certified under the EU-US Data Privacy Framework (see Section 7).

### Data Retention & Control

**Is my data used to train your AI models?**

No. We do not use your content to train, fine-tune or improve any AI models – ours or third parties'. Unless you enable Zero Data Retention, your inputs and outputs may be stored and used solely for Speculative Decoding (see Section 3), which does not involve training any model.

**What happens if I don't enable Zero Data Retention?**

Your API inputs and outputs may be stored and used for Speculative Decoding – and for no other purpose.

**What happens to my data when I stop using the service?**

Upon termination or expiration of the services, we delete or return Customer Personal Data at your choice, except where retention is required by applicable law.

### Legal & Compliance

**Are you GDPR compliant?**

Yes. We are fully committed to and compliant with the GDPR.

**Do I need to sign a separate Data Processing Agreement (DPA)?**

No. Our DPA is an integral part of our Terms of Service: by agreeing to the ToS, you are automatically covered. If you need a countersigned copy for your procurement or regulatory process, contact your account manager.

**Who is my contracting party?**

Nebius B.V., a Netherlands company and a subsidiary of Nebius Group N.V. (NASDAQ: NBIS). The DPA is governed by Dutch law.

**How do I get your SOC 2 report or other security documentation?**

Through our Trust Center ([https://nebius.com/trust-center](https://nebius.com/trust-center) ); certain reports are provided under NDA. Requests from third-party assessors require your authorization.

**How will I know if you change sub-processors?**

We provide at least 15 days' prior notice of any addition or replacement of a sub-processor, and you have the right to object on reasonable data-protection grounds.

**Can commitments such as ZDR or region pinning be recorded in my contract?**

The region commitment for dedicated endpoints is already a binding term of the DPA, which forms part of your agreement. If you require additional contractual documentation – for example, an order form or addendum reflecting your ZDR configuration – contact your account manager.

**Can I process health data or other special-category data?**

Yes, subject to your responsibilities as Data Controller (lawful basis, notices, consents) – see Section 10. For sensitive workloads we recommend Zero Data Retention and a dedicated endpoint; for US healthcare data, see our HIPAA guideline. If you are bound by professional-secrecy rules, contact [privacy@nebius.com](mailto:privacy@nebius.com) first.

### Copyright & Ownership

**Who owns the content I generate or the models I fine-tune?**

You do. You retain all intellectual property rights to your inputs, outputs, and any models you fine-tune or distill on our platform. Note that outputs may not be unique, and other users may receive the same or similar outputs.


# Privacy Policy
Source: https://docs.tokenfactory.nebius.com/legal/privacy-policy



## **Introduction**

This Privacy Policy applies to the personal data that Nebius B.V., a company incorporated under the laws of the Netherlands and having its registered office at Schiphol Boulevard 165, 1118 BG Schiphol, the Netherlands (**“Nebius,” “we,” “us,” or “our”**), processes as a controller in connection with the Nebius Token Factory services (**“Services”**).

This Privacy Policy does not apply to:

* Job applicants. If you are applying for a position with Nebius, please see our separate HR Privacy Policy: [https://docs.nebius.com/legal/hr-privacy-policy](https://docs.nebius.com/legal/hr-privacy-policy).
* Third‑party offerings. Any products, services, or content provided by third parties even other Nebius group entities are governed by their own privacy policies.

## **Terms and Definitions**

This Privacy Policy uses the key terms as defined by the EU General Data Protection Regulation (GDPR). Unless we explicitly state otherwise, these terms carry the same meanings and must be interpreted in accordance with the GDPR. Under the “Learn more” button, you can review detailed definitions of the terminology we use.

<Expandable title="Learn more">
  * **GDPR:** This term stands for General Data Protection Regulation, the EU Regulation (EU) 2016/679 of the European Parliament and of the Council, adopted on 27 April 2016 and in force since 25 May 2018. It sets uniform rules across the European Union for the processing of personal data and the protection of individuals’ privacy rights.
  * **Personal data:** This term means any information relating to an identified or identifiable natural person (“data subject”).
  * **Controller:** This term means means the natural or legal person, public authority, agency or other body which, alone or jointly with others, determines the purposes and means of the processing of personal data.
  * **Performance of the contract:** This term refers to the legal basis provided under Article 6(1)(b) of the GDPR. It means that the processing of personal data is necessary for the performance of a contract between you as a data subject and us, or to take steps at your request before entering into a contract.
  * **Consent:** This term means means any freely given, specific, informed and unambiguous indication of the data subject’s wishes by which they, by a statement or by a clear affirmative action, signify agreement to the processing of personal data relating to them.
  * **Legal obligation:** This term refers to the legal basis provided under Article 6(1)(c) of the GDPR. It means that the processing of personal data is necessary for compliance with a legal obligation to which we, as the controller, are subject.
  * **Legitimate interest:** This term refers to the legal basis provided under Article 6(1)(f) of the GDPR. It means that the processing of personal data is necessary for the legitimate interests pursued by us or a third party. However, we want to clarify that we do not rely on this legal basis unless we have determined that our interests are not overridden by your interests or fundamental rights and freedoms as the data subject that require protection of personal data.
  * **The standard contractual clauses approved by the EU Commission:** This term refers to the appropriate safeguard for transfer of personal data to a third country provided under Article 46(2)(c) of the GDPR. For the purposes hereof, a third country is a country which is not in the EEA territory and is not recognized by the EU Commission as a country that ensures an adequate level of protection.
</Expandable>

## **1. Personal Data We Collect**

### **1.1. Personal Data You Provide to Us**

**Registration.** When you register to use our Services, you provide us with the following data:

* Full name
* Contact information, such as email address and phone number
* Job title
* Company name
* Company size
* Industry
* Any other information you supply in the registration form

**Third‑Party Authentication.** If you choose to sign up using your Google or GitHub account (or another supported third‑party account), you authorize us to receive, store, and use any information that you have permitted the third party to share via its API. This may include, for example, your name, email address, profile picture, and any other data you have agreed to share.

**Model Interaction.** When you interact with our Services through the Nebius Token Factory interface, you submit your inputs via the Nebius Token Factory interface. The categories of processed personal data include:

* Inference planning: Data we can ask on intended use case and/or inference consumption to classify the user
* Speculative decoding: Input(s) and output(s) for the purpose of training smaller models as specified in the [Terms of Service](https://docs.tokenfactory.nebius.com/legal/terms-of-service)

**Service Payments.** When you pay for our Services, we collect and process:

* Payment details
* Billing address (street, city, state/province, postal code, country)
* Tax/VAT identification, if required for invoicing
* Transaction records (dates, amounts, invoice/order numbers, payment status)
* Additional payment-related details you provide

**Contact & Inquiries.** We collect the following information through the web form you complete to contact us or to submit your request or query to us, along with any other details you choose to provide:

* First name
* Last name
* Email address
* Phone number
* Job title
* Company name
* Company website
* Scenario you’re interested in (e.g. infrastructure or inference as a service)
* Any other information you decide to share

**Support Communications.** We collect any information you provide when you communicate with us by email, live chat, support tickets, or other means, including the content of your messages and any associated details.

**Know Your Customer (KYC).** We may ask you to provide information to verify your identity as part of our KYC procedures. This helps us comply with legal and regulatory requirements. You might be asked to submit:

* A partially obscured copy of your government‑issued ID, showing only:
  * Your photograph
  * Your full name and surname
  * Your nationality
  * The place and type of document
  * The first four digits of the document number
* Any other information necessary to complete our KYC checks

### **1.2. Personal Data We Collect Automatically**

**Service Use.** When you use our Services, we automatically collect and generate metadata needed to provide, administer, and improve those services. This may include:

* User identifiers and authentication credentials
* Resource identifiers and related attributes
* IP addresses
* Operational status, software errors, and crash reports
* Quality and performance metrics (e.g., latency, throughput, uptime)
* Other technical details essential for the operation, maintenance, and troubleshooting of our Services
* Marketing preferences
* Zero data retention status

**Cookies and Similar Technologies.** For more details on this matter, please refer to Section 8 hereof.

### **1.3. Submissions on Behalf of Others**

When you provide information on behalf of another person or entity whether during registration or through any other interaction you confirm that you are authorized to:

* Supply and process the submitted details for that person or entity;
* Grant us the right to collect, use, and retain their information in accordance with this Privacy Policy.

By submitting third‑party information, you represent and warrant that you have obtained all necessary consents and permissions from the data subject or entity to permit us to handle their data as described herein.

### **1.4. Sensitive Personal Data**

We do not intentionally collect sensitive personal data (e.g., information revealing race, ethnicity, political opinions, religion, or similar) and ask that data subjects refrain from submitting such information.

## **2. Why We Process Your Personal Data**

We collect and use personal data only for purposes that are necessary to:

* Process your requests and queries
* Verify your identity if you contact us
* Send you our newsletter
* Enhance the performance and content of our websites
* Tailor our services and websites to your preferences
* Analyze trends
* Comply with applicable laws
* Protect us and our users/customers from fraud or other illegal activities

More specifically, we process personal data to:

* Provide timely feedback to your questions and requests and/or take the necessary steps to conclude an agreement with you
* Deliver our Services, including creating, updating, and personalizing your account; enabling accessibility features; processing payments; performing all operations required to provide and maintain the Services; handling support requests and other inquiries; sending notifications about Service changes; and supplying information relevant to your use of the Services
* Develop, improve, and secure our Services, including speculative decoding
* Evaluate the effectiveness of our promotional campaigns so we can better tailor them to your interests
* Conduct analytics, statistics, development, and research, including sharing aggregated statistical data with our business partners and affiliates

All of the above is based on our legitimate interest in providing you with a superior experience and in fine-tuning our offerings to your needs.

Additionally, we may process your personal data to:

* Comply with legal obligations, judicial enforcement, and administrative orders under applicable law
* Protect and enforce our rights, privacy, security, safety, systems, and property as well as those of other persons we are responsible for and to resolve disputes
* Verify your identity during onboarding as part of our KYC (Know-Your-Customer) checks, authenticate you as an authorized user of the Services, and detect or prevent possible fraud
* Perform audits and internal checks to ensure our processes comply with legal, contractual, and regulatory requirements

We also engage in notifications and promotional communications directly related to Nebius Services. We may send you messages about new features, offerings, events, and special opportunities via any contact method available to us (e.g., web notifications, email), through our website, or via marketing campaigns on other platforms, including social media. You can opt out of these communications at any time through the Services settings page or by following the unsubscribe link in our emails.

#### **Consent where required by law**

In certain jurisdictions outside the EEA, local laws may require your explicit consent before we process your personal data. By accessing, browsing, or using our websites, you agree to the processing of your personal data as outlined in this Privacy Policy. You may withdraw your consent at any time your withdrawal will not affect the legality of any processing carried out before you withdrew it.

| **Purpose of processing**                                                                                                                               | **Legal Basis**                                                                                                                | **Example**                                                                                      |
| :------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| Send you our marketing newsletters                                                                                                                      | Consent                                                                                                                        | Monthly newsletter about new Nebius Token Factory features, sent only after prior opt‑in         |
| Improve website performance and content                                                                                                                 | Legitimate interest to improve website performance and content and optimize user experience                                    | Analyzing page‑load times on the Nebius Token Factory (platform) and optimizing server responses |
| Analyze trends                                                                                                                                          | Legitimate interest in analyzing usage trends to anticipate infrastructure needs, and deliver data-driven service enhancements | Shift in query types: e.g., from simple prompts to fine-tuning requests                          |
| Comply with applicable laws and regulations                                                                                                             | Legal obligation                                                                                                               | Retaining financial records to meet tax audit requirements                                       |
| Deliver our services: create/update/personalize your account; process payments; handle support; send service notifications; finalize contracts with you | Contract performance                                                                                                           | Registering a new Nebius Token Factory customer, and charging the service fee                    |
| Verify identity during onboarding (KYC checks)                                                                                                          | Legal obligation                                                                                                               | Performing customer verification checks to comply with anti‑money‑laundering regulations         |

## **3. To Whom We Disclose Your Personal Data**

We may share certain personal data with the following recipients, as required or permitted by applicable law and our legitimate interests:

* **Nebius Group:**\
  For the purposes of providing and developing our services, we may share your personal data within the Nebius Group.
* **Service providers:**\
  We engage third‑party providers to help deliver our Services such as for maintenance, auditing, payment processing, customer support, marketing, and development. These providers may access the personal data they need solely to perform their tasks on our behalf, and they’re contractually prohibited from using or disclosing it for any other purpose. If you purchase Nebius services, we may also use a payment provider who may independently collect additional information about you (for example, for fraud prevention or compliance with legal requirements).
* **Marketing and analytics providers:**\
  With your prior consent, we may share data with marketing and analytics providers (e.g., Google Analytics) to understand and improve how you use our website.
* **Legal Disclosures:**\
  We may disclose your information if required by law, subpoena, or other legal process - or whenever we have a good‑faith belief that disclosure is necessary to:
  * Investigate, prevent, or take action on suspected or actual unlawful activities, or to assist law‑enforcement agencies.
  * Enforce our agreements with you.
  * Defend against third‑party claims or allegations.
  * Protect the security or integrity of our services or those of our affiliates.
  * Safeguard the rights, safety, or property of Nebius, our users, employees, or others.
* **Change in Control or Sale:**\
  We can also share your personal data as part of a sale, merger or change in control, or in preparation for any of these events. Any other entity which buys us or part of our business will have the right to continue to use your data, but only in the manner set out in this Privacy Policy or as required by law.

## **4. Your Rights**

According to the GDPR, you have certain rights as a data subject, including the right to access, right to data portability, right to rectification, right to withdraw consent, right to object, right to erasure, right to restriction of processing, right to lodge a complaint, and right to contact a Data Protection Authority (DPA). Please be aware that there may be limitations or exceptions to these rights, depending on the specific circumstances and legal requirements. If anything is unclear, please don't hesitate to contact us and ask any questions. Below, you can find more information about these rights and how you can exercise them.

<Expandable title="Learn more">
  * **Right of Access** You may request access to the personal data we hold about you. We’ll provide details about how and why we process your data, the categories of data involved, any recipients, and other relevant information.
  * **Right to Data Portability** You may receive the personal data you’ve provided to us in a structured, commonly used, machine‑readable format, and you can request that we transmit it directly to another controller where technically feasible.
  * **Right to Rectification** If you believe your personal data is inaccurate or incomplete, you may request that we correct or update it.
  * **Right to Withdraw Consent** If our processing relies on your consent, you can withdraw it at any time. Withdrawal won’t affect the lawfulness of any processing carried out before you withdrew consent.
  * **Right to Object** You can object to our processing based on legitimate interests or for direct marketing. We will stop processing unless we have compelling legitimate grounds or a legal requirement to continue. Objections to direct marketing are always honored.
  * **Right to Erasure (“Right to Be Forgotten”)** You may request deletion of your personal data unless processing is necessary for freedom of expression and information, compliance with a legal obligation, public‑interest tasks, or the establishment, exercise, or defence of legal claims.
  * **Right to Restrict Processing** You may request that we suspend processing of your personal data if:
    * You contest its accuracy;
    * The processing is unlawful, and you oppose erasure;
    * We no longer need it, but you require it to establish, exercise, or defend legal claims; or
    * You have objected to processing pending verification of our legitimate grounds.
  * **Right to Lodge a Complaint** You may lodge a complaint with the supervisory authority in your country of residence, or with our lead supervisory authority - the Dutch Data Protection Authority (Autoriteit Persoonsgegevens), if you believe we have infringed your rights. You can find a list of local data protection authorities here; for Israel – [https://www.gov.il/en/departments/the\_privacy\_protection\_authority/govil-landing-page](https://www.gov.il/en/departments/the_privacy_protection_authority/govil-landing-page).
</Expandable>

Once you submit a request, we will review and respond promptly - typically within 30 days. In certain cases, we may need additional time to investigate and fulfil your request. Once completed, we will confirm via the email address you provided.

By submitting a request, you confirm that you are the individual to whom the data relates and that you have the legal capacity and authority to act on your own behalf. We may verify your identity using the information you supply if there is any doubt. Additionally, where required by law, we may need to share your request and our response with third parties, including regulatory authorities.

## **5. Retention of Your Personal Data**

We retain your personal data only for as long as it is necessary to fulfil the scopes described in this Privacy Policy. The exact length of time may vary depending on the type of data, the scope of processing, the category of users involved and - most importantly- whether we are compelled to retain certain personal data due to, for example, tax requirements or other legal obligations under applicable law, fraud‑prevention or safety considerations. When we process partially obscured copies of your ID, we retain them for a maximum of 18 months in order to maintain the necessary records for our yearly audits.

Please consider that non‑personal data may be retained and used by Nebius without limitation, in particular for archiving purposes, public‑interest, statistical, historical or scientific research purposes.

## **6. Overseas Personal Data Transfers**

We store your personal data in our data centres in the European Union. However, as a global organization, we may also process and transfer your personal data to other group companies or to third parties around the world for the purposes set out in this Privacy Policy - specifically, to fulfil our agreements with you, to respond to your requests, or, where applicable, based on your consent.

Whenever we transfer your personal data outside the EU and EEA, we ensure its protection by implementing appropriate safeguards, including:

* adopting the European Commission’s Standard Contractual Clauses (and their approved equivalents for Switzerland and the UK), or other approved transfer mechanisms;
* encrypting personal data in transit;
* maintaining internal policies to restrict access and promote awareness.

For an overview of data‑protection standards by country, please visit [https://www.cnil.fr/en/data-protection-around-the-world](https://www.cnil.fr/en/data-protection-around-the-world).

## **7.  Data Privacy Framework**

### **7.1. Participation in Data Privacy Framework**

Your personal data may be transferred to and processed in countries other than the country in which you are resident. These countries may have data protection and privacy laws that are different to the laws of your country.

We have taken appropriate safeguards to require that your personal data will remain protected in accordance with this Privacy Policy. These include implementing the European Commission’s Standard Contractual Clauses for transfers of personal data between our group companies, which require all group companies to protect personal data they process from the European Economic Area (EEA) in accordance with European Union data protection law.

Nebius complies with the EU-U.S. Data Privacy Framework (EU-U.S. DPF) as set forth by the U.S. Department of Commerce. Nebius has certified to the U.S. Department of Commerce that it adheres to the EU-U.S. Data Privacy Framework Principles (EU-U.S. DPF Principles) with regard to the processing of personal data received from the European Union in reliance on the EU-U.S. DPF. If there is any conflict between the terms in this Privacy Policy and the EU-U.S. DPF Principles the Principles shall govern. To learn more about the Data Privacy Framework (DPF) program, and to view our certification, please visit [https://www.dataprivacyframework.gov/](https://www.dataprivacyframework.gov/).

### **7.2. Types of personal data collected**

Please refer to the Section 1 “Personal Data We Collect” to find out about the types of personal data collected by Nebius under the Data Privacy Framework.

### **7.3. Commitment to be subject to the Data Privacy Framework Principles**

Nebius is committed to being subject to the Data Privacy Framework Principles for all personal data received from the European Union in reliance on the relevant part(s) of the Data Privacy Framework program.

### **7.4. Purposes for collection and use of personal data**

Please refer to the Section 1 “Personal Data We Collect” to find out about the purposes for which Nebius collects and uses personal data under the Data Privacy Framework.

### **7.5. How to contact us about any inquiries or complaints regarding Data Privacy Framework compliance**

In compliance with the EU-U.S. DPF Nebius commits to resolve DPF Principles-related complaints about our collection and use of your personal information. EU individuals with inquiries or complaints regarding our handling of personal data received in reliance on the EU-U.S. DPF should first contact Nebius at:

DPO’s contact details: Marina Benassi Coslovi, [privacy@nebius.com](mailto:privacy@nebius.com)

Address: Schiphol Boulevard 165, 1118 BG Schiphol, the Netherlands

Email: [privacy@nebius.com](mailto:privacy@nebius.com)

Phone: +31 202066970

### **7.6. independent dispute resolution**

In compliance with the EU-U.S. DPF Nebius commits to cooperate and comply respectively with the advice of the panel established by the EU data protection authorities (DPAs) with regard to unresolved complaints concerning our handling of personal data received in reliance on the EU-U.S. DPF to the EU-U.S. DPF.

### **7.7. The type or identity of third parties to which we disclose personal information under the Data Privacy Framework, and the purposes for which we do so**

Please refer to the Section 3 “To Whom We Disclose Your Personal Data” to find out about the type or identity of third parties to which we disclose personal data under the Data Privacy Framework, and the purposes for which we do so.

### **7.8. Your right to access your personal data**

You also have the right to access any personal data that relates to you and which is processed under the Data Privacy Framework. Further information about this right can be found in the “Your rights” section below.

### **7.9. Your choices regarding use of your personal data Under the Data Privacy Framework:**

* You have the right to opt out of the disclosure of your "non sensitive" personal data to third party controllers and/or to the use of it for a purpose that is materially different from the purpose(s) for which it was originally collected or subsequently authorized by you.
* You have the right to only have “sensitive” personal data about you disclosed to third party controllers and/or used for a purpose that is materially different from the purpose(s) for which it was originally collected or subsequently authorized by you through exercise of opt-in choice.
* For personal data processing that is controlled by Nebius, these choices can be exercised by contacting Nebius through the methods noted in the “Your rights” section below.

### **7.10. Subjection to the investigatory and enforcement powers of the Unite States Federal Trade Commission (FTC)**

The Federal Trade Commission has jurisdiction over Nebius compliance with the EU-U.S. Data Privacy Framework (EU-U.S. DPF).

### **7.11. Possible use of binding arbitration**

You have the possibility, under certain conditions, to invoke binding arbitration for complaints regarding Data Privacy Framework compliance not resolved by any of the other Data Privacy Framework mechanisms. For additional information about this, please see here.

### **7.12. Requirement to disclose personal data in response to lawful requests by public authorities**

Please be aware that Nebius may be required to disclose personal data that relates to you (and which is protected under the Data Privacy Framework) in response to lawful requests by public authorities including to meet national security or law enforcement requirements.

### **7.13. Nebius liability in cases of onward transfers to third parties**

Nebius may transfer personal data for the purposes described in the Section 3 “To Whom We Disclose Your Personal Data” to a third party acting as a data controller or as an agent. If we intend to disclose personal data to a third party acting as a data controller or as an agent we will comply with, and protect, personal data as provided in the Accountability for Onward Transfer Principle of the Data Privacy Framework.

Nebius remains liable for the processing of personal data received under the Data Privacy Framework and subsequently transferred to a third party acting as an agent if the agent processes such personal data in a manner inconsistent with the Data Protection Framework principles, unless we prove that we are not responsible for the event giving rise to the damage.

### **7.14. Nebius U.S. Entities Covered by Data Privacy Framework Certification**

Nebius complies with the EU-US Data Privacy Framework. To learn more, see the relevant sections (Section 7 and 14) of the current Privacy Statement, and visit the U.S. Department of Commerce’s Data Privacy Framework website.

For the purposes of our Data Privacy Framework certification, the below subsidiaries of Nebius are in scope:

* **Nebius Inc**., 10 State Street, Newburyport, MA 01950, United States
* **ADC Tech Inc.**, 10 State Street, Newburyport, MA 01950, United States

## **8.  Cookies**

As outlined in our [Cookie Policy](https://docs.nebius.com/legal/cookie-policy), we use cookies and similar technologies such as pixels, ad tags and local storage to improve your experience, provide convenience, maintain security and serve you tailored ads. For simplicity, we call all these tools “cookies.” In practice, cookies support functions like authentication, security, feature enablement, advertising and analytics. There are two types of cookies: first‑party cookies set by us, and third‑party cookies set by our vetted partners.

We collect marketing and analytics cookies based on your consent obtained via the cookie banner. If you’ve granted consent for cookies, you may modify or withdraw that consent at any time via the “Manage cookies” option on our websites.

### **Third‑Party Services**

Certain features of the websites are provided by third parties. These providers may collect information about your online activity to deliver personalized advertisements for products and services that might interest you.

In addition, your activity on our websites may enable third parties such as search engines to infer your interests and show you tailored ads as you browse. Any data collection and processing by these third parties is governed solely by their own privacy policies, for which they are fully responsible. Nebius disclaims all liability for their practices. Please consult each third party’s Privacy Policy for more details.

## **9. Security of Your Personal Data**

Nebius maintains a dedicated security team and employs a combination of technical, administrative and physical controls to safeguard the personal data we process. We continually update and rigorously test these measures to ensure they remain state‑of‑the‑art.

However, no system is completely impervious to attack, and no internet transmission can be guaranteed secure. While we strive to protect your data, we cannot promise that unauthorized access, hacking, data loss or other breaches will never occur. Any transmission of information is at your own risk.

## **10. State- or Country-Specific Provisions**

### **10.1. United States of America**

#### **A. Privacy Information for California Residents**

This section of the Privacy Policy applies only to California residents. If you are a California resident, this section will prevail over other parts of the Privacy Policy in case of any discrepancies. To avoid any misunderstanding, personal information has the same meaning as personal data.

**Personal Information Collected over the Last 12 Months**

Personal information we collected directly from you:

| **Categories of data collected**                                             | **Data collected from you and why it was collected**                                                                                                                     |
| :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Characteristics of protected classifications under California or Federal law | We do not intentionally collect any information on your protected classifications                                                                                        |
| Commercial information                                                       | Records of services with Nebius                                                                                                                                          |
| Precise Geolocation Data                                                     | We do not collect precise geolocation data                                                                                                                               |
| Financial Information                                                        | Payment and Billing Information. Please note that Nebius relies on third‑party payment providers to handle your payments and does not retain your payment information    |
| Biometric Data                                                               | We do not collect biometric data                                                                                                                                         |
| Audio, electronic, visual, thermal, olfactory, or similar information        | Audio may be recorded during online calls, provided that the party being recorded has given their consent                                                                |
| Internet/Network Activity                                                    | Internet Protocol address (IP address), browser type and language, sending and exiting pages, information about the date and time stamps, information about visits, logs |
| Professional or Employment-related Information                               | Field of activity or occupation, job title, and company name                                                                                                             |
| Education Information                                                        | We do not collect Education Information                                                                                                                                  |
| Device Information                                                           | Operating system, browser type, device ID (with consent)                                                                                                                 |

**Categories of Personal Information Sold in the last 12 months**

We do not sell your personal information to third parties.

**Categories of Personal Information Disclosed over the last 12 months**

| **Categories of Data Disclosed**                                                                                                                               | **Types of Entities to Which Data Was Disclosed**  | **Reason for Disclosure of Data**                  | **Categories of Recipients**                       |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- | :------------------------------------------------- | :------------------------------------------------- |
| Commercial information, Financial information, Internet/Network Activity Professional or Employment-related Information, Audio Information, Device Information | Please see section 3 with the detailed description | Please see section 2 with the detailed description | Please see section 3 with the detailed description |

**Information we sell**

Nebius does not sell your personal information to third parties. “Sale” excludes transfers that occur as part of a merger, acquisition, asset sale or other similar business transaction involving all or part of Nebius. In such cases, your personal information may be transferred to the acquiring entity. If a transaction will materially change how we process your personal information, we will notify you beforehand.

**Your California Privacy Rights**

We have implemented policies and procedures to help facilitate the exercise of privacy rights available to California residents under applicable law. If you are a California resident, you are entitled to the rights described in Section 4 of this Privacy Policy. In addition, you may be entitled to the following:

* **Disclosure of Direct Marketers**
  <Expandable title="Learn more">
    California law allows California residents once a year to request information regarding our disclosure of your personal information, if any, to third parties for their direct marketing purposes during the preceding calendar year. This information includes: a. The categories of information we disclosed to third parties for their direct marketing purposes during the immediately preceding calendar year; b. The names and addresses of third parties that received the information; and c. If the nature of the third party’s business cannot be determined from their name, to obtain examples of the products or services marketed.
  </Expandable>
* **Right to Information About Collecting, Selling, Sharing, or Disclosing Personal Information**

  <Expandable title="Learn more">
    Upon receipt of a verifiable request, you may obtain a list of:

    * the specific pieces of your personal information that Nebius holds;
    * the categories of personal information collected about you, sold to third parties, or disclosed to third parties for business purposes;
    * the categories of personal information sold within the last 12 months;
    * the categories of sources from which personal information is collected;
    * the business or commercial purpose for collecting or selling personal information; and
    * the categories of third parties with whom personal information is shared, sold, or disclosed for a business purpose.
  </Expandable>
* **Right to Opt-Out of the Sale of Personal Information**
  <Expandable title="Learn more">
    California residents have the right to opt-out of the sale of their personal information under certain circumstances.
  </Expandable>
* **Right to Non-Discrimination**
  <Expandable title="Learn more">
    As defined under relevant law, you have a right to non-discrimination in the services or quality of services you receive from us for exercising your rights. Please contact us with the use of contact details specified in Section 15 of this Privacy Policy if you wish to exercise these rights. Note that we may ask you to verify your identity - such as by requiring you to provide information about yourself - before responding to such requests.
  </Expandable>
* **Submitting a Verifiable Request under the CCPA**
  <Expandable title="Learn more">
    California residents have certain rights regarding their personal information under the California Consumer Privacy Act of 2018 ("CCPA"). Nebius will respond to an individual's "verifiable request" to exercise their rights under the CCPA - that is, when Nebius has received a request purporting to be from a particular individual, and Nebius has been able to verify the individual's identity. The need to verify an individual's identity is crucial to protecting your information and ensuring that it is not shared with someone pretending to be you or not authorized to act on your behalf. You may submit a verifiable request using the contact details specified in Section 15 of this Privacy Policy. To process your request, we will ask you to provide information to help us verify your identity. This information may include your name, address, whether you have an account with Nebius, and any other information deemed necessary to reasonably verify your identity. Once we have your submission, we will compare the information you provide to the information we have on file to verify your identity. If necessary, we may request additional information if we have difficulty confirming your identity. We will not share your information or fulfil any requests if we are unable to confirm that a request is a "verifiable request". If we cannot verify your identity, we will not be able to process your request.
  </Expandable>
* **Submitting a request through an authorized agent**
  <Expandable title="Learn more">
    Under California law, a California resident can appoint an “authorized agent” to submit certain verifiable requests on their behalf, such as the right to know what information we collect or to request the deletion of the consumer's information. An authorized agent may submit a request by following the steps outlined above. An authorized agent may submit a request by following the steps outlined above. However, the agent must identify the consumer they are acting on behalf of and provide the information necessary for us to verify the consumer’s identity. Additionally, we will require the authorized agent to submit proof of their authorization to act on the consumer’s behalf. To ensure the security and privacy of your information, we will request that you provide written consent for the person acting as your authorized agent. This consent may include us contacting you directly to confirm that the individual claiming to be your agent has your permission to access or delete your information. We will also verify your identity independently to ensure that an unauthorized person is not attempting to exercise your rights without permission. We will not share your information or honour any requests in situations where you have not provided written authorization for an agent to act on your behalf, or where we are unable to verify your identity.
  </Expandable>
* **Submitting a Request for Removal of Minor Information**

  <Expandable title="Learn more">
    To request the removal of information about a minor from Nebius, parents or guardians may submit a request with the subject line “Removal of Minor Information.” This request must come from the minor’s parent or guardian; minors themselves may not submit information to us via email. Your submission should include the following details:

    * the nature of your request
    * the identity of the content or information to be removed
    * whether the content or information is found
    * the location of the content or information (e.g., providing the URL of the specific web page where the content or information is found)
    * a statement that the request is related to the “Removal of Minor Information”
    * your name, street address, city, state, ZIP code, and email address If we become aware that a minor has provided personal data or otherwise used by Nebius in violation of the Privacy Policy, we will take steps to remove that information. Please note that our websites and services are not intended for use by individuals under the age of 18.
  </Expandable>

**Our Policy on "Do Not Track" Signals under the California Online Protection Act**

We do not support Do Not Track (DNT). DNT is a preference you can set in your web browser to inform websites that you do not wish to be tracked. You can enable or disable DNT by visiting the “Preferences” or “Settings” section of your web browser.

Please note that third parties may collect data about you. We cannot control how third parties respond to Do Not Track signals or other similar mechanisms. The collection and use of data by third parties, and their responsiveness to Do Not Track signals, is governed by their respective privacy policies.

#### **B. Privacy Information for Residents of other States (Colorado, Connecticut, Delaware, Indiana, Iowa, Kentucky, Maryland, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon, Tennessee, Texas, Utah, and Virginia)**

Unless otherwise stated by the law of your state of residence, the provisions in Chapter A “Privacy Information for California Residents” will apply to the processing of your data. If you have questions related to your rights or any other aspects of this Privacy Policy, please contact us using the methods outlined in Section 14.

Your Rights under various United Sates state data privacy laws such as the Colorado Privacy Act, Connecticut Data Privacy Act, Delaware Personal Data Privacy Act, Indiana Consumer Data Protection Act, Iowa Consumer Data Protection Act, Kentucky Consumer Data Protection Act, Maryland Online Data Privacy Act, Minnesota Consumer Data Privacy Act, Montana Consumer Data Privacy Act, Nebraska Data Privacy Act, New Hampshire SB 255, New Jersey SB 332, Oregon Consumer Privacy Act, Tennessee Information Protection Act, Texas Data Privacy and Security Act, Utah Consumer Privacy Act, and the Virginia Consumer Data Protection Act.

For residents from the states of Colorado, Connecticut, Delaware, Indiana, Iowa, Kentucky, Maryland, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon, Tennessee, Texas, Utah, or Virginia this section allows you to exercise your rights under the applicable state law.

* **Right to Confirm:** The right to confirm whether your personal data is being processed.
* **Right to Access / Disclosure:** The right to have access to your personal data upon simple request – that is, you may receive a copy of such data upon receipt of a verifiable request, along with other information related to the processing of your data.
* **Right to Data Portability:** the right to obtain, move, copy, or transfer data as defined by applicable law.
* **Right to Correction/Rectification:** The right to correct your personal data if you find it is inaccurate, incomplete or obsolete.
* **Right to Deletion:** The right to obtain the deletion of your personal data in the situations set forth by applicable data protection law.
* **Right to Opt-Out:** The right to opt out of the processing of your personal data for targeted advertising, as defined by applicable law as well as the right to opt out of the processing of sensitive data as defined by applicable law. Certain applicable laws also permit the right to opt out of the sale of personal data and profiling.
* **Right to Appeal:** You may also have the right to appeal the denial of any of these rights by submitting a form that will be provided to you if we deny a data request.
* Submitting a Verifiable Request under the United States’ State Laws.

<Expandable title="Learn more">
  Residents of the above-mentioned states have certain rights regarding their personal information under applicable law. Nebius will respond to an individual's "verifiable request" to exercise their rights under these applicable laws - that is, when Nebius has received a request purporting to be from a particular individual, and Nebius has been able to verify the individual's identity. The need to verify an individual's identity is crucial to protecting your information and ensuring that it is not shared with someone pretending to be you or not authorized to act on your behalf.

  You may submit a verifiable request using the contact details specified in Section 15 of this Privacy Policy. To process your request, we will ask you to provide information to help us verify your identity. This information may include your name, address, whether you have an account with Nebius, and any other information deemed necessary to reasonably verify your identity.

  Once we have your submission, we will compare the information you provide to the information we have on file to verify your identity. If necessary, we may request additional information if we have difficulty confirming your identity.

  We will not share your information or fulfil any requests if we are unable to confirm that a request is a "verifiable request". If we cannot verify your identity, we will not be able to process your request.

  Not all requests will be fulfilled. Nebius is committed to complying with each and every data privacy protection law. However, in some circumstances, consumers are not entitled to certain requests. Nebius will hear all appeals if an appeal right is permitted under applicable law (e.g. the Tennessee Information Protection Act).
</Expandable>

#### **C. Profiling Disclosure**

We do not engage in profiling of consumers in furtherance of automated decisions that produce legal or similarly significant effects, as those terms are defined under the Colorado Privacy Act.

#### **D. Data Protection Assessments**

Nebius will conduct all necessary data protection assessments for all applicable processing or other activities when required by applicable law

### **10.2. Israel**

This section provides additional information for residents of Israel in accordance with the Protection of Privacy Law, 5741-1981 as amended by Amendment No. 13, 5774–2024 (the “PPL”).

**Terminology:** For the purpose of this section, the term “Information” is used, which is equivalent to “Personal Data” under the GDPR.

**Local Representative:** For purposes of the Protection of Privacy Law, our appointed local representative in Israel is:

Nebius Israel Ltd

Yigal Alon Street 94, 1 Alon Tower, 39 floor, Tel-Aviv, Israel (Attn: Privacy Office)

Email: [privacy@nebius.com](mailto:privacy@nebius.com)

**Supervisory Authority:** You have the right to lodge a complaint with the Israeli Privacy Protection Authority at any time by using the contact details specified here.

## **11. Children**

Our websites and services are not intended for use by individuals under the age of 18. We do not knowingly collect or process personal data from anyone under 18. If you are a parent or guardian of a minor and believe we have collected their data, you may contact us to exercise their rights as described in this Privacy Policy.

## **12. Difficulty Accessing this Privacy Policy**

If you have a disability and cannot access our Privacy Policy online, please contact us (using the details in the Section 14) to request a copy in an alternative, more accessible format. We will not collect or process any health‑related or other sensitive personal data in connection with such requests.

## **13. Changes**

Our business is continually evolving, and we may update this Privacy Policy to reflect those changes. We’ll post any revised version on our website, so we encourage you to review it periodically. If we make any material changes, we will notify you.

## **14. Contact Us**

If you have any questions or concerns about your privacy, you may contact us or our data protection officer by writing to us at:

Nebius B.V., Schiphol Boulevard 165, 1118 BG Schiphol, the Netherlands (Attn: Privacy Office), or by emailing us at [privacy@nebius.com](mailto:privacy@nebius.com).

***

Web address: [https://docs.tokenfactory.nebius.com/legal/privacy-policy](https://docs.tokenfactory.nebius.com/legal/privacy-policy)

Publication date: December 5, 2025\
Effective date: December 5, 2025

<Expandable title="previous versions of the document">
  Previous version of the document:  [https://docs.tokenfactory.nebius.com/legal/archive/privacy-policy-20250812](https://docs.tokenfactory.nebius.com/legal/archive/privacy-policy-20250812)
  \
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/privacy-policy-20250401](https://docs.tokenfactory.nebius.com/legal/archive/privacy-policy-20250401)
  \
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/privacy-policy-20240828](https://docs.tokenfactory.nebius.com/legal/archive/privacy-policy-20240828)
</Expandable>


# List of Sub-Processors
Source: https://docs.tokenfactory.nebius.com/legal/subprocessors



**Internal Sub-processors (Legal Entities of Nebius Group):**

| **Name of Sub-processor**       | **Services Performed**                             | **Sub-processor Location** |
| ------------------------------- | -------------------------------------------------- | -------------------------- |
| Nebius DC Oy                    | Cloud infrastructure                               | Finland                    |
| Nebius Inc.                     | Cloud infrastructure; Service Maintenance; Support | United States              |
| Nebius Israel Ltd.              | Cloud infrastructure; Service Maintenance; Support | Israel                     |
| Nebius CZ s.r.o.                | Service Maintenance; Support                       | Czech Republic             |
| Nebius GmbH                     | Service Maintenance; Support                       | Germany                    |
| Nebius UK Ltd.                  | Cloud infrastructure; Service Maintenance; Support | United Kingdom             |
| Tech Hub IL Ltd.                | Service Maintenance; Support                       | Israel                     |
| EdTech Plus Tech d.o.o. Beograd | Service Maintenance; Support                       | Serbia                     |

**External Sub-processors:**

| **Name of Sub-Processor**                       | **Purpose of Processing**                                                                                 | **Entity Location** | **Hosting location** | **Sub-Processor Privacy Documentation\***                                                                                                                                                                                                   |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stripe Payments Europe, Ltd.                    | Payment processing                                                                                        | Ireland             | United States        | [Privacy Policy](https://stripe.com/en-nl/privacy)<br />[List of Sub-Processors](https://stripe.com/nl/legal/preview/service-providers)                                                                                                     |
| Hubspot, Inc.                                   | Customer Relations Management Delivery of customer communications, such as in-product messages and emails | United States       | European Union       | [Privacy Policy](https://legal.hubspot.com/privacy-policy)<br />[List of Sub-Processors](https://legal.hubspot.com/sub-processors-page)                                                                                                     |
| Atlassian Pty Ltd. (Jira, Confluence)           | Customer support and ticket handling                                                                      | Australia           | European Union       | [Privacy Policy](https://www.atlassian.com/legal/privacy-policy)<br />[List of Sub-Processors](https://www.atlassian.com/legal/sub-processors)                                                                                              |
| Slack Technologies, LLC                         | Customer communications Customer support                                                                  | United States       | European Union       | [Privacy Policy](https://slack.com/intl/en-gb/trust/privacy/privacy-policy)<br />[List of Sub-Processors](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/misc/salesforce-infrastructure-and-subprocessors.pdf) |
| Factiva Limited (Dow Jones)                     | Managed compliance screening service                                                                      | United Kingdom      | United States        | [Privacy Policy](https://www.dowjones.com/privacy-notice/)                                                                                                                                                                                  |
| Oracle Corporation (Netsuite)                   | Billing and Accounting                                                                                    | United States       | United States        | [Privacy Policy](https://www.oracle.com/legal/privacy/privacy-policy/)                                                                                                                                                                      |
| Microsoft Corporation (Microsoft 365, Sentinel) | Customer communications Security Information and Event Management                                         | United States       | European Union       | [Privacy Policy](https://www.microsoft.com/en-gb/privacy/privacystatement)<br />[List of Sub-Processors](https://servicetrust.microsoft.com/DocumentPage/8d295fc2-f7d9-4662-8301-99b077fc6b79)                                              |
| RunPod Inc.                                     | Cloud Infrastructure                                                                                      | United States       | Iceland              | [Privacy Policy](https://www.runpod.io/legal/privacy-policy)                                                                                                                                                                                |
| Eigen AI, Inc.                                  | AI inference services                                                                                     | United States       | United States        | [Privacy Policy](https://www.eigenai.com/privacy-and-service)                                                                                                                                                                               |
| BoostRun, LLC                                   | Cloud infrastructure                                                                                      | United States       | United States        | [Privacy Policy](https://boostrun.com/terms-of-service.html)                                                                                                                                                                                |
| Shadeform, Inc.                                 | Cloud infrastructure                                                                                      | United States       | United States        | [Privacy Policy](https://shadeform.com/privacy-policy)                                                                                                                                                                                      |
| Argentum AI, Inc.                               | Cloud infrastructure                                                                                      | United States       | United States        | Upon request                                                                                                                                                                                                                                |

*\* Sub-Processor Privacy Documentation includes links to their privacy policies and the list of sub-processors (where available online).* 

**Summary of changes** 

The following updates describe how the list of sub-processors has changed compared with the previous version of this document. 

| Date         | Changes                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| May 11, 2026 | Added: BoostRun, LLC, external sub-processor Shadeform, Inc., external sub-processor Argentum AI, Inc., external sub-processor |

Web address: [https://docs.tokenfactory.nebius.com/legal/subprocessors](https://docs.tokenfactory.nebius.com/legal/subprocessors)

**Effective date:** May 11, 2026\
**Last updated:** May 11, 2026

<Expandable title="previous versions of the document">
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/subprocessors-20250821](https://docs.tokenfactory.nebius.com/legal/archive/subprocessors-20250821) \
  Previous version of the document: [https://docs.tokenfactory.nebius.com/legal/archive/subprocessors-20250812](https://docs.tokenfactory.nebius.com/legal/archive/subprocessors-20250812)
</Expandable>


# Terms of Service
Source: https://docs.tokenfactory.nebius.com/legal/terms-of-service



### 1. PREAMBLE 

Welcome to Nebius Token Factory! Our platform provides services that allow its Customers to use artificial intelligence models for content generation purposes alongside with a range of complementary services . 

These Terms of Service constitute a legally binding agreement (hereinafter - the “Agreement” or the “Terms”) entered into by and between Nebius B.V., a Dutch limited liability company with registered address at Schiphol Boulevard 165, 1118 BG Schiphol, the Netherlands (the “Company”, also referred as ‘We”, “Us” or “Our”), and any person who accesses and uses our Platform or our Service (“You” or the “Customer”). 

These Terms apply to any use and/or access to our Service by You. By using or accessing our Service, you agree to comply with and be bound by these Terms. If you do not agree with these Terms, you are not permitted to use or access the Service. 

### 2. DEFINITIONS 

**“Account”** means a unique record created for Customer that provides access to the Service and describes the financial relationship between the Company and the Customer. It maintains unified records of the Service used, containing billing information, including payments made by the Customer and amounts payable under these Terms. 

**“Adapter”** means an object that is designed to be compatible with the designated Model and intended to adjust the Model Output in accordance with the algorithm contained within the Adapter. 

**“Applicable Data Protection Laws”** means all laws, regulations, rules and guidance related to privacy, data protection and the processing of personal data in general, which apply to the offering and providing the Service. 

**“API”** means a set of protocols and tools that enables customers to send Input to Model and receive Output. 

**“API Keys”** means unique identifiers provided by the Company to the Customer to authenticate and authorize their access to the API. 

**“Authorized User”** means any End User who has been explicitly designated by the Customer and granted specific administrative rights and permissions to manage the Services; 

**“Customer”** means any natural person or legal entity that purchases and pays for the Service. 

**“Customer’s Product”** means any product, service, application, or system developed, managed, or distributed by the Customer that utilizes or integrates with Our Service. 

**“Customer’s Content”** means Inputs and Outputs, Your Adapters, Your Fine-Tuned Models, Your Distilled Models, Your Datasets , Your Models and Your smaller Models for Speculative Decoding. 

**“Dataset”** means any collection of data that is used for training, validating, fine-tuning Models or other purposes, and includes both datasets that are provided by the Customer and uploaded to the Platform, as well as those datasets that are created or generated by the Customer on the Platform itself during the provision of the Service. 

**“Distillation”** means the process of training a smaller Model to replicate the behavior of a larger Model while maintaining similar performance characteristics. 

**“Distilled Model”** means the resulting Model created through Distillation. 

**“End User”** means any individual allowed by Customer to access and use the Service, subject to compliance with the Terms. 

**“EU AI Act”** means “Regulation of the European Parliament and of the Council laying down harmonised rules on artificial intelligence (Artificial Intelligence Act) and amending certain Union legislative acts” COM/2021/206. 

**“EULA”** means a license agreement, an acceptable use policy and any other similar document published by a Model’s provider and governing the use of the Model. 

**“Fine-Tuned Model”** means a Model that has undergone Fine-Tuning. 

**“Fine-Tuning”** means the process of adapting Model to enhance its performance on specific tasks or Datasets. 

**“Input”** means any data, text, image, audio, video query, or other information that you submit through the Service to prompt the Models. 

**“Linked Documents”** means documents which are an integral part of this Agreement and apply to the Service by reference. The Linked Documents are specified in Section 22 of this Agreement. 

**“Model”** means any computational algorithm, system, or framework developed to analyze data and learn patterns for performing specific tasks, including but not limited to prediction, classification, generation, or decision-making. 

**“Personal Data”** means any information relating to an (directly or indirectly) identified or identifiable individual, as defined by Applicable Data Protection Laws. 

**“Platform”** means software and hardware platform that provides means to use the Service that is available via: [https://tokenfactory.nebius.com](https://tokenfactory.nebius.com) 

**“Prompt Preset”** means a predefined configuration that includes one or more input prompts along with associated generation parameters (such as temperature, Model type, maximum tokens, etc.), enabling users to save and reuse specific combinations of settings for consistent interactions with a Model. 

**“Order Form”** means a written or electronic document issued by Nebius to Customer under this Agreement, specifying the services to be provided, payment model, fees, and any other applicable terms. Each Order Form shall incorporate and be governed by the terms and conditions of this Agreement, unless expressly stated otherwise. 

**“Output”** means any data, text, image, audio, video results, or other information generated by the Models in response to the Input provided by the Customer through the Service. 

**“Service”** means the provision of access to and use of Models and related functionalities through the Platform. 

**“Speculative Decoding”** means an inference-time method that speeds up Output generation by using a smaller (“draft”) Model to propose multiple tokens, which are then verified or rejected by a larger (“target”) Model. Speculative decoding reduces the number of steps the target Model must compute while preserving its Output quality and significantly increases the speed of the Service while maintaining the quality of the Model’s responses. 

### 3. SCOPE OF THE SERVICE 

**a.** Our Service provides Customer with the inference from available Models via web interface, software development kits or API. Customers can set an Input and a set of parameters, which may depend on the Model. In response, the Customer receives an Output. 

**b.** Requests can be made through the following methods: 

* **API**. Each request must include the Customer’s unique API Key to ensure proper authentication and authorization. 
* **Software development** **kits** are sets of tools and libraries that help implement Our API in various programming environments (**hereinafter – the ‘SDKs’**). 
* **Web interface** provides a user interface for Customers to interact with Our Service directly. Customers can input data and parameters directly through the web interface and receive immediate responses. 
* **Web Application** offers an integrated platform where Customers can access and utilize Service through provided interactive environment. 

**c.** Customers acknowledge and agree that, by using Our Service, they are interacting with an AI system as defined by the EU AI Act. Customers are obliged to inform End Users of this clause prior to their use of the Service. 

**d.** Customers may bring their own Adapters, Models and smaller Models for Speculative Decoding for using them on Service in accordance with Section 12 hereof. 

**e.** Customers may initiate Fine-Tuning or Distillation of a Model through the Platform by submitting their Datasets and configuring the required parameters in accordance with Section 13 hereof. 

### 4. API AND SDK USAGE 

**a.** The Company grants the Customer a worldwide, revocable, non-exclusive, non-sublicensable, and non-transferable right to use the API and SDKs for the term of the Agreement. This right is granted for the purpose of incorporating the API and SDK into the Customer’s Product in order to make the Service available via the Customer’s Product. 

**b.** The right to use API and SDKs includes the right to allow End Users to use the Service through Customer’s Product. 

**c.** The Customer is responsible for informing its End Users about these Terms when using the Service through Customer’s Product. 

### 5. CUSTOMER RESPONSIBILITIES 

**a. Account creation:** to access and use the Service provided on the Platform, You must create an Account using your e-mail address and complete the onboarding form available on the Platform. It is essential that You provide accurate, complete, and current information during the registration process. You are also responsible for ensuring that the information in Your Account remains up to date. If any changes occur, You must promptly update your Account information to maintain its accuracy and integrity. 

**b.** To use Our API or SDK, you will need an API key. You are responsible for maintaining the security of Your API key and for any activity that occurs while using Your API key. 

**c. Age limitation:** to create an Account and use the Service, You must be at least 18 years old. By registering an Account, You confirm that you meet this age requirement. 

**d.** If the Customer is a legal entity, the person executing these Terms confirms that they have the right, power, and authority to execute documents and contractually bind the entity. 

**e. Rate Limits.** We may enforce rate limits on API requests to ensure fair usage of the Service. You agree not to exceed these rate limits. 

**f. Restrictions.** The Customer will not: 

* Use our Service for any illegal, unlawful, prohibited purposes, including but not limited to providing an illegal service, terrorism, illegal hate speech, child pornography, violation of consumer protection rights, violation of privacy and data protection rights, violation of advertising laws or causing harm to third parties or the Company. 
* Use or access the Service to develop a product or service that competes with the Service or engage in competitive analysis or benchmarking. 
* Reverse engineer, decompile, disassemble, modify, or create derivative works from the source code underlying the Service. 
* Use the Service as or in a high-risk AI system or in prohibited AI practices as defined in the EU AI Act. 
* Transfer, distribute, resell, lease, license, or assign the Service, or offer the Service on a standalone basis. 
* Make API requests that exceed the specified limits on number and frequency, impose an unreasonable or disproportionately heavy load on the API or Service, or negatively impact the ability of others to access or use the API or Service. 
* Attempt to probe, scan, or test the vulnerability of the Service, breach security or authentication measures without proper authorization, or intentionally render any part of the Service unusable. 
* Infringe the rights of third parties, including but not limited to intellectual property rights or privacy. 
* Use, modify, copy, reproduce, create derivatives of, or distribute the Service, including Output, in whole or in part, for (a) any military purposes, (b) purposes of surveillance, including any research or development relating to surveillance, (c) biometric processing. 
* Use the Service in violation of applicable laws or outside the scope expressly permitted by these Terms. 

**g.** **Customer Obligations.** Customer using our Platform and/or our Service should: 

* Adhere to all applicable local, national, and international laws and regulations. 
* Maintain the confidentiality of Account credentials and notify Us of any unauthorized use. 
* Use the Service as intended and in accordance with the Terms and ensure that all End Users also comply with these Terms. 
* Pay for the Service on terms agreed upon. Ensure timely payment to maintain uninterrupted access to the Service. 

### 6. SERVICE FEES AND PAYMENT PROCEDURE 

**a.** Unless specific fees are agreed by the Parties in an Order Form, the applicable fees are available on the Platform. 

**b.** The Service is provided on a pre-paid basis. Customer is required to deposit funds into their Account by performing a bank card transaction. For each deposit, You will need to enter your bank card details and the desired deposit amount. The deposit must be used within one year after it is made, as it will expire afterward. 

**c.** The Company may, at its sole discretion, provide the Customer with free credits to try the Service. The Company reserves the right to grant, modify, or revoke these free credits at any time and without prior notice. 

**d.** Access to certain specific Models may require the deposit of funds into the Customer’s Account and will not be possible using free credits. The availability and terms for accessing these Models will be specified on the Platform and are subject to change at the Company’s discretion. 

**e.** Each Party will be responsible, as required under applicable law, for identifying and paying all taxes and other governmental fees and charges that are imposed upon or with respect to the transactions and payments under these Terms. All fees payable by the Customer are exclusive of Taxes, except where applicable law requires otherwise. 

**f.** Before the first deposit, We will request and determine your country of residence, whether you are a natural person or a legal entity, and your tax identification number (if applicable). This information is necessary to ensure compliance with tax regulations and to apply the appropriate pricing and applicable taxes. An invoice will be issued immediately upon successful charging of Your bank card. The invoice will detail the deposit amount, taxes (if applicable), and the total charged amount. Taxes are applied on top of the deposited and service fees amount. 

**g.** The Customer will be liable to pay or reimburse the Company for any taxes, interest, penalties, or fines arising out of any misdeclaration or misinformation provided by the Customer to the Company. 

### 7. DATA USAGE AND STORAGE 

By using the Service, You grant Us a license to access, use, host, cache, store, copy , and modify Inputs and Outputs for the purposes of providing the Service. These rights and licenses are royalty free, transferable, sub-licensable, and worldwide. The Company reserves the right, and has absolute discretion, to remove, screen, or delete any of Your Inputs and Outputs at any time, for any reason, and without notice. 

As part of providing the Service, the Company collects and processes both Input and Output data for the purpose of training smaller Models used exclusively for Speculative Decoding. 

If you prefer that we (i) do not store Your Inputs and Outputs for the purposes of providing the Service and (ii) do not collect and process  them for Speculative Decoding, You may opt out at any time. You can indicate your preference through the opt-out mechanism available in the onboarding form or by submitting a request to the Company’s support team via email at [tokenfactory-support@nebius.com](mailto:tokenfactory-support@nebius.com). Please be aware that opting out may, in some cases, limit the Service’s ability to address Your specific use case effectively. 

### 8. PERSONAL DATA 

**a. Data Controller.** We will process any Personal Data that You submit when registering for an Account and logging into it, in our capacity as data controller under Applicable Data Protection Laws. Such processing is governed by our Privacy Policy [https://docs.tokenfactory.nebius.com/legal/privacy-policy](https://docs.tokenfactory.nebius.com/legal/privacy-policy), and is necessary to establish, manage, administer, execute and enforce these Terms. 

To the extent that personal data of the Parties’ representatives is processed in order to perform the Service and manage this Agreement, each Party shall comply fully with all Applicable Data Protection Laws. Customer shall ensure that all such representatives are provided with the information set out in the Privacy Policy. 

**b. Data Processor.** When Company processes Personal Data on Your behalf and under Your instructions, the terms of the Data Processing Agreement available at [https://docs.tokenfactory.nebius.com/legal/dpa](https://docs.tokenfactory.nebius.com/legal/dpa) (“Data Processing Agreement”), shall apply and form an integral part of these Terms. 

You shall submit the Input in compliance with all applicable laws and governmental rules and regulations, including without limitation Applicable Data Protection Laws, and You shall obtain such consents or other legal permissions as are required by Applicable Data Protection Laws and the Data Processing Agreement. 

**c.** In the event the Customer uses any Services in connection with Protected Health Information (“PHI”) or electronic Protected Health Information (“ePHI”), as those terms are defined in the Health Insurance Portability and Accountability Act of 1996 (“HIPAA”), the Customer must read and abide by the Nebius Token Factory HIPAA Implementation Guideline [https://docs.tokenfactory.nebius.com/legal/hipaa-guideline](https://docs.tokenfactory.nebius.com/legal/hipaa-guideline). 

### 9. SERVICES ACCESS. SUSPENSION OR TERMINATION OF THE ACCESS 

**a.** The Customer shall be responsible for assigning and managing roles of Authorized Users as described on the Platform including maintaining an up-to-date list of such End Users, and shall promptly revoke or amend associated access rights when no longer required. 

**b.** You may terminate your access to the Service by sending 10-day prior written notice by email to Our support [tokenfactory-support@nebius.com](mailto:tokenfactory-support@nebius.com). Upon the termination date, all your access to your Account and our Service will cease and You will remain responsible for all fees and charges You have incurred through the termination date. Upon any such termination You will not be entitled to a refund of any pre-paid Fees. 

**c.** We may suspend or terminate your access to the Service, if You violate these Terms, fail to pay fees, or if required by law. We will provide notice of suspension or termination when possible. 

**d.** We may terminate your access without cause by providing a prior written notice to You. In this case, We will refund any unconsumed prepaid fees. 

### 10. INTELLECTUAL PROPERTY 

**a.** The Company holds exclusive ownership of all rights, titles, and interests (including intellectual property rights) in and to the Platform, the Service and any of their elements, excluding third parties’ and Your Models, but including smaller Models for Speculative Decoding created by the Company. 

**b.** You hold exclusive ownership of all rights, titles, and interests (including intellectual property rights) to Customer’s Content. You acknowledge that Your Outputs may be not unique and other users of the Service may receive the same or similar Outputs. 

**c.** We do not claim any rights to Customer’s Content, except as described in Sections 7, 12, 13 and 13A. 

**d.** If Customer or End User provides the Company with any suggestions, enhancement requests, recommendations or other feedback regarding the Service, the Company shall have a fully paid-up, royalty-free, worldwide, transferable, sub-licensable, assignable, irrevocable and perpetual license to implement, use, modify, commercially exploit, incorporate into the Service or otherwise use them. The Company also reserves the right to seek intellectual property protection for any features, functionality or components that may be based on or that were initiated by suggestions, enhancement requests, recommendations or other feedback regarding the Service that the Company receives from Customer and End Users. 

### 11. MODELS 

**a.** The Service provides Customers with the ability to interface with Models. We do not guarantee the accuracy, reliability, validity or appropriateness of the Outputs generated by these Models. 

**b.** Customers acknowledge and agree that the use of the Output is at their own risk and discretion. 

**c.** Models we provide may be subject to their own EULA, and it is your responsibility to comply with those EULAs available in Models’ cards, which are hereby incorporated by reference into this Agreement. 

### 12. YOUR ADAPTERS AND MODELS 

**a.** Your Models, Your smaller Models for Speculative Decoding, and Your Adapters will only be accessible for use by You. The Company has a right to use them only for the purpose of making them available to You via the Service. 

**b.** The use of Your Models, Your smaller Models for Speculative Decoding, and Your Adapters via Service is subject to the following: (i) the Company does not guarantee that Your smaller Models for Speculative Decoding and Your Adapters will function as intended or be compatible with the designated Model; (ii) the Company reserves the right to impose a limit on the number of Your Models, Your smaller Models for Speculative Decoding, and Your Adapters that can be used by You at any given time; (iii) the Company has a right to delete Your Models, Your smaller Models for Speculative Decoding, and Your Adapters from the Service any time. 

**c.** The use of Your Adapters and Your smaller Models for Speculative Decoding is restricted to a predefined list of Models specified by the Company. 

**d.** The Company is not responsible for ensuring the functionality or performance of Your Models, Your smaller Models for Speculative Decoding, and Your Adapters , including but not limited to compatibility with the Services, Outputs produced by them. 

**e.** You are solely responsible for: i. Ensuring that Your Adapters and Your smaller Models for Speculative Decoding are properly designed and compatible with the specified Model; ii. Complying with all applicable laws and regulations in connection with the creation and use of Your Models, Your smaller Models for Speculative Decoding, and Your Adapters ; iii. Compliance with respective EULA in connection with the creation and use of Your Models, Your smaller Models for Speculative Decoding, and Your Adapters . You represent and warrant that you have all necessary rights to use Your Models, Your smaller Models for Speculative Decoding, and Your Adapters  and authorize the Company to use them as described in this Section 12. 

### 13. FINE-TUNING AND DISTILLATION 

**a.** Fine-Tuned or Distilled Models will only be accessible for use by the Customer who created them. The Company has a right to use Your Datasets only for the purpose of Fine-Tuning or Distillation and a right to use Your Fine-Tuned or Distilled Model only for the purpose of making it available to You via the Service. 

**b.** The use of Fine-Tuned or Distilled Models via Service is subject to the following: (i) the Company reserves the right to impose a limit on the number of Fine-Tuned or Distilled Models that can be used by the Customer at any given time; (ii) the Company has a right to delete Your Fine-Tuned or Distilled Model from the Service upon providing You with at least three (3) days prior written notice, or immediately if required by applicable law, security concerns, or risk of harm to the Service. 

**c.** Fine-Tuning and Distillation are restricted to a predefined list of Models specified by the Company. 

**d.** The Company is not responsible for ensuring the functionality or performance of Fine-Tuned or Distilled Models, including but not limited to Outputs produced by such Fine-Tuned or Distilled Models. 

**e.** Customers are solely responsible for: i. Ensuring that the  Datasets You upload comply with all applicable laws, regulations and the Agreement; ii. Compliance with respective EULA in connection with the creation and use of Fine-Tuned or Distilled Models. Customer represents and warrants that the Customer has all necessary rights to use training and validation Datasets and Fine-Tuned or Distilled Models and authorize the Company to use them as described in this Section 13. 

### 13A. PROFESSIONAL SERVICES 

**a.** The Company may, at the Customer’s request, provide professional services related to the optimization, deployment, and management of Models and associated infrastructure (“Professional Services”). These Professional Services may include but are not limited to: model-to-GPU optimization, model-level optimization, API-level optimization, model training services (such as fine-tuning, distillation, and training of custom models to improve latency and quality) and pipeline quality improvement (including prompt engineering, task decomposition, retrieval pipeline optimization, and retrieval-augmented generation). 

**b.** Professional Services may be provided upon written request by the Customer to the Company’s designated email address for Professional Services, as specified by the Company from time to time, or by execution of an Order Form mutually agreed upon and signed by both parties. 

**c.** All Models and Adapters created or modified in course of Professional Services shall be deemed Your Models and Your Adapters. If the Professional Services result in the creation or modification of a General Purpose AI (GPAI) model, as defined under the EU AI Act, the Customer shall be deemed the provider of this GPAI model and shall bear all corresponding obligations under applicable law, including but not limited to the EU AI Act. 

**d.** The Company has a right to use Your  Datasets that are provided in accordance with this Section 13A, solely for the purpose of  providing Professional Services. Customers are solely responsible for: i. Ensuring that the training and validation Datasets You upload comply with all applicable laws, regulations and the Agreement; ii. Compliance with respective EULA in connection with the creation and use of modified Models. Customer represents and warrants that the Customer has all necessary rights to use n Datasets and Fine-Tuned or Distilled Models and authorize the Company to use them as described in this Section 13A. If the provision of the Professional Services involves Customer Content that includes Personal Data, the provisions of Section 8 and the Data Processing Agreement shall also apply to such services. 

### 14. THIRD-PARTY SERVICES 

In addition to Models, the Service may contain third party components and services, including links to other web sites (“Third-Party Services”). Such Third-Party Services are offered by third parties with separate legal notices or governed by other agreements. The Company is not responsible and cannot be held liable for the availability (or lack of availability) of Third-Party Services. If the Customer chooses to interact with the Third-Party Services made available through the Service, such third-party’s terms will govern their relationship with the Customer and the Customer will be responsible for its compliance with such third party’s terms. The Company is not responsible or liable for Third-Party Services or for such third parties’ terms or actions. 

### 15. ACCEPTABLE USE POLICY FOR FLUXDEV MODEL 

**a.** In addition to all other provisions of these Terms, the use of the FluxDev Model must comply with the limitations and requirements outlined in FluxDev Acceptable Use Policy available via link: [https://docs.tokenfactory.nebius.com/legal/flux-dev](https://docs.tokenfactory.nebius.com/legal/flux-dev). 

### 16. DISCLAIMER 

TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE SERVICE, THE OUTPUTS AND ANY CONTENT, MATERIALS PROVIDED BY US OR OUR SUPPLIERS ARE OFFERED “AS IS” AND “AS AVAILABLE”, WITHOUT WARRANTIES OR GUARANTEES OF ANY KIND. WE MAKE NO REPRESENTATIONS OR WARRANTIES REGARDING THE SERVICE AND OUTPUTS, INCLUDING BUT NOT LIMITED TO THE QUALITY, SUITABILITY, ACCURACY, OR COMPLETENESS OF ANY CONTENT, INFORMATION, PRODUCT, OR SERVICE PROVIDED THROUGH THE SERVICE. ALL REPRESENTATIONS AND WARRANTIES, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, ARE EXPRESSLY DISCLAIMED. 

WE OR OUR SUPPLIERS DO NOT WARRANT THAT THE SERVICE AND OUTPUTS ARE ERROR-FREE, FREE OF VIRUSES, OR OTHER HARMFUL COMPONENTS, OR THAT DEFECTS WILL BE CORRECTED. WE OR OUR SUPPLIERS DO NOT GUARANTEE THE QUALITY, ACCURACY, TIMELINESS, TRUTHFULNESS, COMPLETENESS, OR RELIABILITY OF ANY PART OF THE SERVICE. WE OR OUR SUPPLIERS ALSO DO NOT ENSURE THAT THE SERVICE WILL BE UNINTERRUPTED, SECURE, OR OPERATE AT ANY PARTICULAR SPEED. 

WE MAY SUSPEND, WITHDRAW, DISCONTINUE, OR CHANGE ALL OR ANY PART OF THE SERVICE WITHOUT NOTICE. 

### 17. LIMITATION OF LIABILITY 

WE AND OUR AFFILIATES OR LICENSORS SHALL NOT BE HELD LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES, INCLUDING, BUT NOT LIMITED TO, LOSS OF PROFITS, GOODWILL, DATA, USE, OR OTHER INTANGIBLE LOSSES, EVEN IF WE HAVE BEEN INFORMED OF THE POTENTIAL FOR SUCH DAMAGES. OUR TOTAL LIABILITY UNDER THESE TERMS WILL BE LIMITED TO THE GREATER OF EITHER THE AMOUNT YOU PAID FOR THE SERVICE THAT CAUSED THE CLAIM WITHIN THE 12 MONTHS PRECEDING THE INCIDENT OR FIVE HUNDRED DOLLARS (\$500). THESE LIMITATIONS APPLY ONLY TO THE FULLEST EXTENT ALLOWED BY APPLICABLE LAW. 

### 18. INDEMNIFICATION 

YOU WILL DEFEND, HOLD HARMLESS AND INDEMNIFY US, OUR EMPLOYEES, AFFILIATES, LICENSORS AND EACH OF THEIR RESPECTIVE EMPLOYEES, OFFICERS, DIRECTORS FROM ANY AND ALL LOSSES ARISING OUT OR RELATING TO ANY THIRD PARTY CLAIMS (INCLUDING THIRD-PARTY MODEL PROVIDERS) CONCERNING: YOUR USE OF THE SERVICE, AND/OR THIRD-PARTY MODEL; ANY CONTENT YOU UPLOAD TO THE SERVICE, INCLUDING BUT NOT LIMITED TO CUSTOMER’S CONTENT; YOUR BREACH OF THIS AGREEMENT AND/OR ANY TERMS AND CONDITIONS OF DATA PROCESSING AGREEMENT; YOUR VIOLATION OF ANY LAW OR THE RIGHTS OF ANY THIRD PARTY IN CONNECTION WITH THE SERVICE. 

### 19. CONFIDENTIALITY 

**a.** Each Party agrees to maintain the confidentiality of all Confidential Information disclosed by the other Party. “Confidential Information” means: (i) all information, whether in written, oral, electronic, visual, or other form, disclosed or made available by one Party to the other Party that: (a) is marked, designated, or otherwise identified as confidential at the time of disclosure; (b) is by its nature confidential or proprietary; or (c) under the circumstances of disclosure, the receiving Party should reasonably understand to be confidential; (ii) including but not limited to trade secrets, know-how, inventions, technical data, employee information, customer and supplier data, business plans, marketing strategies, financial information, proprietary information, and any other commercially sensitive information. For the avoidance of doubt, all information disclosed prior to the execution of this Agreement that meets the above criteria shall also be considered Confidential Information. 

**b.** Each Party shall use the Confidential Information solely for the purposes of fulfilling its obligations under this Agreement and shall not disclose it to any third party without the prior written consent of the disclosing Party, except as necessary to comply with applicable laws or regulations. 

**c.** The receiving Party agrees to protect the confidentiality of the disclosing Party’s Confidential Information in the same manner that it protects its own confidential information of like kind, but in no event using less than reasonable care. 

**d.** The obligations of confidentiality shall not apply to information that: (i) is or becomes publicly known through no act or omission of the receiving Party; (ii) was in the receiving Party’s lawful possession prior to the disclosure and had not been obtained by the receiving Party either directly or indirectly from the disclosing Party; (iii) is lawfully disclosed to the receiving Party by a third party without restriction on disclosure; or (iv) is independently developed by the receiving Party without use of or reference to the disclosing Party’s Confidential Information. 

**e.** Upon termination of these Terms, the receiving Party shall return or destroy all copies of the Confidential Information at the request of the disclosing Party, subject to any legal obligations to retain such information. 

### 20. GOVERNING LAW 

These Terms and any attached or Linked Documents shall be governed and construed in accordance with the laws of the Netherlands. All disputes arising out of or in connection with these Terms shall be solely submitted to the courts of Amsterdam. 

### 21. CHANGES 

**a.** The Company reserves the right to modify, amend, or update these Terms at any time. Any changes will be effective immediately upon posting on our Platform or through the Service. 

**b.** We will provide notice of any significant changes to these Terms. Notice may be provided via email, through the Service, or by posting a notice on our Platform. It is your responsibility to review the Terms periodically for any updates or changes. 

### 22. MISCELLANEOUS 

**a. No agency.** These Terms do not create any agency, partnership relations, joint activity relations, employment, or any other relations between the Customer and the Company that are not expressly stipulated in the Agreement. 

**b. Severability.** If any term (or part of term) of the Terms and/or any document referred to in the Terms is invalid, void, illegal, and unenforceable, the rest of the Terms and any document referred to in the Terms will remain in effect. 

**c. No waiver.** Neither Party will be treated as having waived any rights by not exercising (or delaying the exercise of) any rights under the Terms and/or any document referred to in the Terms. 

**d. Assignment.** The Customer may not assign any part of the Terms or the documents referred to in the Terms without prior written consent of the Company. The Company reserves the right to assign, transfer, or delegate any of its rights, duties, or obligations under these Terms to another company or entity, provided that the Company notifies the Customer of such assignment in writing at least ten (10) calendar days in advance. The Customer acknowledges and agrees that such assignment shall not relieve the Company of its obligations under these Terms, and the assigned entity shall assume all rights, duties, and obligations of the Company herein. 

**e. Anticorruption clause.** The Parties adhere to the applicable anticorruption laws. The Parties hereby acknowledge and confirm that they have adopted a policy of zero tolerance to bribery and corruption, involving a total ban on any corrupt practices and on any facilitation payments. The Parties, their affiliates, employees, as well as intermediaries and representatives directly or indirectly involved in performance of the Parties’ obligations (including agents, commission agents, customs brokers and other third parties), shall not accept, pay, offer to pay, allow or authorize the payment/acceptance of any funds or transfer of any benefits (including intangible benefits), directly or indirectly, to/from any persons for the purpose of influencing any actions or decisions with the intention of obtaining any improper advantage, including bypassing any legally prescribed procedure or pursuing other illegal purposes. This clause constitutes the Parties’ representations. Either Party may unilaterally withdraw from the Agreement if the other violates the obligations stipulated by this clause. If a Party suspects that any provisions of this clause have been or might be violated, the Party concerned undertakes to immediately notify the other of its suspicions in writing. 

**f. Sanctions.** The Customer and their End Users shall comply with all applicable export, trade, economic and financial laws and regulations, including those administered and enforced by the United States, European Union (“EU”) and relevant Member States, the United Kingdom, the United Nations Security Council or any other government bodies with jurisdiction over the Customer’s activities (collectively “Sanctions”). Customer declares that neither Customer nor its subsidiaries, nor their respective directors, officers, employees, or affiliates is identified on any applicable government list of restricted or prohibited parties, nor is owned or, where relevant under applicable Sanctions, controlled by the same (“Sanctions Targets”). The Сustomer will not, directly or indirectly, engage in any unauthorized business or dealings with any Sanctions Targets or otherwise engage in any activities prohibited by Sanctions. The Customer is responsible for ensuring compliance of their End User to this clause’s provisions. 

Should the Customer or any of its End Users become a Sanctions Target or should the Company reasonably determine that it cannot perform its obligations under this Agreement due to Sanctions-related prohibitions (each a “Sanctions Event”), the Company may terminate this Agreement effective immediately. 

**g. Force Majeure.** Except for the inability to meet financial obligations, neither party will be deemed in breach of this Agreement for any cessation, interruption, or delay in the performance of its obligations due to causes beyond its reasonable control (“Force Majeure Event”). Force Majeure Events include, but are not limited to, earthquakes, floods, natural disasters, acts of God, labor disputes, civil disturbances, terrorism, war (declared or undeclared), cyber attacks (such as denial of service attacks), or the inability to obtain necessary supplies, transportation, or other essential commodities or services. 

Additionally, changes in or the adoption of any law, regulation, judgment, or decree will also constitute a Force Majeure Event. 

### 23. LINKED DOCUMENTS

[Data Processing Agreement Nebius Token Factory](https://docs.tokenfactory.nebius.com/legal/dpa)

[Nebius Token Factory HIPAA Implementation Guideline](https://docs.tokenfactory.nebius.com/legal/hipaa-guideline)

### 24. CONTACT INFORMATION 

Nebius B.V. \
A Dutch limited liability company with registered address at Schiphol Boulevard 165, 1118 BG Schiphol, the Netherlands. 

Web address: [https://docs.tokenfactory.nebius.com/legal/terms-of-service](https://docs.tokenfactory.nebius.com/legal/terms-of-service)

Publication date: **January** **13, 2026**\
Effective date: **January** **13, 2026**

<Expandable title="previous versions of the document">
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20251104](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20251104)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20251010](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20251010)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250812](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250812)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250401](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250401)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250304](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250304)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250120](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20250120)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20241220](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20241220)
  \
  Previous version of the document:\
  [https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20240828](https://docs.tokenfactory.nebius.com/legal/archive/terms-of-service-20240828)
</Expandable>


# Model Deprecation Jun 22
Source: https://docs.tokenfactory.nebius.com/model-deprecation-jun-22



Some AI models will no longer be available in Nebius Token Factory as part of Public Serverless Endpoints.

## **[​](https://docs.tokenfactory.nebius.com/other-capabilities/deprecation-info#deprecation-timeline)Deprecation timeline**

<Note>
  **On Jun 22, 2026 affected model APIs and UI will be disabled**
</Note>

## **[​](https://docs.tokenfactory.nebius.com/other-capabilities/deprecation-info#models-affected)Models affected**

| moonshotai/Kimi-K2.5-fast               |
| :-------------------------------------- |
| moonshotai/Kimi-K2.5                    |
| deepseek-ai/DeepSeek-V3.2-fast          |
| deepseek-ai/DeepSeek-V3.2               |
| openai/gpt-oss-120b-fast                |
| MiniMaxAI/MiniMax-M2.5-fast             |
| Qwen/Qwen3-235B-A22B-Thinking-2507-fast |
| Qwen/Qwen3.5-397B-A17B-fast             |
| Qwen/Qwen3-Next-80B-A3B-Thinking-fast   |
| zai-org/GLM-5                           |
| PrimeIntellect/INTELLECT-3              |

### **What you should do**

* Review your current usage for any dependencies on deprecated models
* Migrate to supported models available in the platform
* Reach out to our Sales Team to discuss Dedicated Endpoints if the option you’re looking for is not available at the platform.

For production workloads, higher stability requirements, or custom configurations, we recommend using [**<u>Dedicated Endpoints</u>**](https://tokenfactory.nebius.com/?modals=create-dedicated-endpoint "https://tokenfactory.nebius.com/?modals=create-dedicated-endpoint"), which provide:

* Full control over model versions
* Predictable performance and scaling
* Enterprise-grade reliability and isolation

***

### **Need help?**

If you’re impacted or want to ensure a smooth transition, our team is ready to help

* **Contact our Sales team:** [**<u>Link</u>**](https://nebius.com/services/token-factory/enterprise-grade-inference?_gl=1*1d02gz7*_gcl_aw*R0NMLjE3NjY1MDAzMzEuQ2p3S0NBaUFtS25LQmhCckVpd0FhcUFuWnhlWUQ5SnlFVW9hS3Q0UUNOZ1ZpRDQzSms0clNFQVdRRTVHTGV4bHU5anNsUFQwNDFjTVBCb0N0UkVRQXZEX0J3RQ..*_gcl_au*MTM3MTMzODczMi4xNzY2NDc5NjA3LjE1MzYzOTEyOTAuMTc3NDAwNjAxMS4xNzc0MDA2MDEw#token-factory-enterprise-sales-form "https://nebius.com/services/token-factory/enterprise-grade-inference?_gl=1*1d02gz7*_gcl_aw*R0NMLjE3NjY1MDAzMzEuQ2p3S0NBaUFtS25LQmhCckVpd0FhcUFuWnhlWUQ5SnlFVW9hS3Q0UUNOZ1ZpRDQzSms0clNFQVdRRTVHTGV4bHU5anNsUFQwNDFjTVBCb0N0UkVRQXZEX0J3RQ..*_gcl_au*MTM3MTMzODczMi4xNzY2NDc5NjA3LjE1MzYzOTEyOTAuMTc3NDAwNjAxMS4xNzc0MDA2MDEw#token-factory-enterprise-sales-form")
* **Contact our Support team:** [**<u>tokenfactory-support@nebius.com</u>**](mailto:tokenfactory-support@nebius.com)


# Billing & Consumption
Source: https://docs.tokenfactory.nebius.com/other-capabilities/billing-new



## Set up billing

When you sign up for **Nebius Token Factory**, you are prompted to create a **billing account** during onboarding. Billing setup is mandatory—you cannot complete onboarding without it.

**Setting up a billing account requires a bank card.** You can view and update your billing details at any time on the **Billing** page.

Upon first sign-up, you receive **\$1 in trial credit**, valid for **30 days**.

***

## Payment methods

### Bank card

If your payment method is a bank card, you can manually top up your balance at any time.

#### Automatic charging

When using a bank card, Nebius Token Factory debits your balance in real time. Your card is automatically charged in either of the following cases:

* At the start of the month, if your balance is negative
* When the configured billing threshold is reached

The charge amount is calculated to bring your balance back to zero.

If a card charge fails, your account is **suspended**. To avoid service interruptions, ensure that your payment method remains valid and up to date.

### Bank transfer

If your payment method is bank transfer, you can top up your balance manually.

To do so, request a **proforma invoice** from the Nebius sales team.

At the beginning of each month, you will also receive an invoice for the previous month’s usage. If your balance was negative at the end of that month, you must pay the invoice using the payment details provided.

> **Note:** Bank transfers are available to companies only and are not supported for individual accounts.

### Changing your payment method

* To change your bank card, go to **Organisation → Billing details**, then click **Edit**.
* If you are a company, you can switch your payment method to **bank transfer** by contacting support.

***

## Topping up your balance

To avoid automatic charging, you can manually top up your balance at any time:

1. Click **Top up** in the top-right corner of the header bar
2. Enter the amount to add, or choose the **Promo code** option
3. Review your card details and click **Continue**

Once the top-up is completed, the funds are available immediately.

### Applying a promo code

A promo code provides free Nebius Token Factory credits and is typically issued as part of a special offer. Promo codes usually have an expiration date—make sure to apply them before they expire.

Promo codes **cannot be used to pay outstanding invoices**. Any unpaid invoices must still be settled separately.

To apply a promo code:

1. In the navigation menu, click your **balance**
2. Click **Top up**
3. Select **With promo code**
4. Enter the promo code and click **Top up**

After a successful application, your balance increases by the promo code amount.<br />You can verify this in the **Transactions** section.

***

## Consumption Monitoring

You can monitor spending across projects, services, and resources on the **Usage** tab of the **Organisation** page in the web console.

To view detailed charts:

1. Click the chart icon on the right
2. Select an entity type and time period using the filters
3. Hover over chart columns to see usage details for a specific period

You can further refine results using **region**, **project**, **service**, and **product** filters.

***

## Taxes

Depending on your or your company location, the usage of Nebius AI Cloud resources might be subject to taxes such as Value Added Tax (VAT).

### Netherlands

Companies registered in the Netherlands and residents of the Netherlands are subject to 21% VAT.

VAT amount is listed on invoices on a separate line in USD. We also convert it into EUR and show on another line — it is the same VAT in another currency.

### Another EU country

<Tabs>
  <Tab title="Company">
    Nebius does not add VAT or other taxes to your charges.
  </Tab>

  <Tab title="Individual">
    VAT amount is calculated in accordance with your country's tax law. It is listed on invoices on a separate line in USD and repeated on another line in EUR.
  </Tab>
</Tabs>

### United States

For residents of Texas and Washington, Nebius calculates taxes in accordance with United States tax law. For details, see [State and Local Sales Tax Rates](https://taxfoundation.org/data/all/state/sales-tax-rates). Residents of other states are not charged.

The tax amount is listed on invoices on a separate line in USD.

### The rest of the world

<Tabs>
  <Tab title="Company">
    Nebius does not add VAT or other taxes to your charges.
  </Tab>

  <Tab title="Individual">
    At the moment, Nebius does not add VAT or another taxes to your charges.

    In the future, we will calculate the taxes in accordance with your country tax law. The taxes amount will be listed on invoices on a separate line in USD.
  </Tab>
</Tabs>


# Custom speculator
Source: https://docs.tokenfactory.nebius.com/post-training/custom-speculator



Use the Custom Speculator API to train a speculative decoding drafter for a supported base model in Token Factory. A custom speculator job produces a drafter artifact that can be served with vLLM for speculative decoding.

## Create a custom speculator job

Create a fine-tuning job with `method.type="spec-draft"` and provide speculator hyperparameters under `method.spec_draft.hyperparameters`.

```python theme={null}
from openai import AsyncOpenAI

job_request = {
    "model": "Qwen/Qwen3-30B-A3B-Instruct-2507",
    "training_file": training_file,
    "method": {
        "type": "spec-draft",
        "spec_draft": {
            "hyperparameters": {
                "batch_size": 8,
                "learning_rate": 0.0075,
                "n_epochs": 1,
                "warmup_ratio": 0.1,
                "max_grad_norm": 1.0,
                "context_length": 8192,
                "loss": {"type": "kl"},
                "num_decoding_heads": 3,
                "architecture": "eagle3_original",
            },
        },
    },
    "seed": 2214,
    "suffix": "specdec-example",
}

client = AsyncOpenAI(
    base_url="<base_url>",
    api_key="<token>",
)

job = await client.fine_tuning.jobs.create(**job_request)
```

## Dataset format

Only pretokenized datasets are supported. Upload a JSONL file where each line contains:

* `input_ids` — array of token IDs.
* `attention_mask` — array of `1`s and `0`s aligned with `input_ids`.
* `labels` — array of target token IDs. Use `-100` to ignore a position in the loss.

```jsonl theme={null}
{"input_ids": [1, 14, 52, 16], "attention_mask": [1, 1, 1, 1], "labels": [-100, -100, 52, 16]}
{"input_ids": [160, 34, 129, 10432], "attention_mask": [1, 1, 1, 1], "labels": [160, 34, 129, 10432]}
```

## Request fields

### Top-level fields

| Field           | Type    | Required | Description                                                |
| --------------- | ------- | -------- | ---------------------------------------------------------- |
| `model`         | string  | Yes      | Base model to train the speculator against.                |
| `training_file` | string  | Yes      | Training dataset file ID.                                  |
| `method`        | object  | Yes      | Fine-tuning method configuration. Use `type="spec-draft"`. |
| `seed`          | integer | No       | Random seed for reproducibility.                           |
| `suffix`        | string  | No       | Custom suffix for the resulting job or artifact name.      |

### Method fields

| Field                               | Type   | Required | Description                          |
| ----------------------------------- | ------ | -------- | ------------------------------------ |
| `method.type`                       | string | Yes      | Must be `spec-draft`.                |
| `method.spec_draft.hyperparameters` | object | Yes      | Speculator training hyperparameters. |

### Hyperparameters

| Field                | Type    | Description                                                                                                             |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `batch_size`         | integer | Training batch size. A large batch size (e.g. `32`) is recommended.                                                     |
| `learning_rate`      | number  | Optimizer learning rate. `0.0075` is recommended for models under 100B parameters; use a lower value for larger models. |
| `n_epochs`           | integer | Number of training epochs.                                                                                              |
| `warmup_ratio`       | number  | Fraction of total steps used for learning-rate warmup.                                                                  |
| `max_grad_norm`      | number  | Gradient clipping threshold.                                                                                            |
| `context_length`     | integer | Maximum sequence length used during training.                                                                           |
| `num_decoding_heads` | integer | Number of speculative decoding heads to train. Supported values: `1`–`7`.                                               |
| `architecture`       | string  | Drafter architecture. Supported value: `eagle3_original` & `eagle3`.                                                    |
| `loss.type`          | string  | Speculator training loss. Supported values: `kl`, `lk_alpha`, `lk_hybrid`.                                              |

## Supported architectures

| Architecture      | Description                                                                      |
| ----------------- | -------------------------------------------------------------------------------- |
| `eagle3`          | TokenFactory-optimized variant. Can only be served on the TokenFactory platform. |
| `eagle3_original` | Reference implementation. Portable to any vLLM-supported platform.               |

## Supported losses

Set the training loss with `loss.type`. Supported values:

* **`kl`** — Standard Kullback-Leibler divergence loss between drafter and target model logits.
* **`lk_alpha`** — LK loss with KL disabled.
* **`lk_hybrid`** — Weighted combination of KL and LK losses.

## Training metrics

Custom speculator jobs report two categories of metrics:

* **Loss metrics** for monitoring optimization and model behavior during training.
* **Sampling performance metrics** for estimating speculative decoding quality and efficiency.

<Note>
  Some per-head metrics are reported conditionally. For a given head, the metric is computed under the assumption that all previous speculative tokens were accepted. For example, metrics for head 4 are conditioned on tokens 1 through 3 being accepted.
</Note>

### Loss metrics

The following loss metrics are reported during training:

| Metric                     | Description                                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `lk` (per head)            | LK loss for each decoding head.                                                                                        |
| `kl` (per head)            | Kullback-Leibler divergence loss between drafter and target model logits.                                              |
| `cross_entropy` (per head) | Cross-entropy loss for each decoding head.                                                                             |
| `target_model_loss`        | Cross-entropy loss of the target model. Useful for understanding how the target model behaves on the provided dataset. |
| `draft_loss`               | Main speculative decoding training loss reported for the job.                                                          |

<Info>
  All of the losses above are reported regardless of which `loss.type` is selected.
</Info>

### Sampling performance metrics

Each decoding head reports the following sampling performance metrics:

| Metric              | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `acceptance_rate`   | Expected probability that the speculative token from that head is accepted. |
| `number_of_tokens`  | Expected accepted token length.                                             |
| `system_efficiency` | Speculative decoding efficiency, measured as `#tokens / #decoding_heads`.   |

### Metric variations

Sampling metrics may be reported for multiple evaluation variations:

<AccordionGroup>
  <Accordion title="default">
    Standard sampling with `temperature=1.0`. Use this variation to understand expected acceptance behavior under normal sampling.
  </Accordion>
</AccordionGroup>

## Output artefacts

A completed custom speculator job produces the following artifact structure:

```text theme={null}
checkpoint/
  model.safetensors  # speculator weights
  config.json        # speculator configuration
```

To download the resulting artefacts, see [Download checkpoints and model files](https://docs.tokenfactory.nebius.com/post-training/how-to-fine-tune#7-download-checkpoints-and-model-files).

## Serving with vLLM

Serve the resulting artifact with vLLM by passing it through `--speculative-config`:

```bash theme={null}
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --speculative-config '{"model": "checkpoints/draft_heads/eagle3_custom_v1.0/", "num_speculative_tokens": 3, "method": "eagle3"}'
```

<Warning>
  **Eagle weight tying.** For Eagle-based architectures, weights are tied across heads. Only one head's weights are stored in the artifact, even when the model was trained with multiple decoding heads (e.g. `num_decoding_heads=3`).

  As a result, the speculator can be served with any `num_speculative_tokens` value from `1` to `N`, but it typically performs best when `num_speculative_tokens` matches or is lower than the number of decoding heads used during training.
</Warning>

### Tuning `ntokens`

Set `ntokens` close to the observed acceptance rate to balance speculation against compute overhead. For example, if `ntokens=7` yields an acceptance rate of \~3.86, dropping to `3` or `4` will typically improve throughput.


#  Dataset formats for fine-tuning
Source: https://docs.tokenfactory.nebius.com/post-training/datasets



You can create datasets for training a model. Nebius Token Factory supports the [JSON Lines](https://jsonlines.org/) format (`.jsonl`) for dataset files. You can use one of the following dataset types:

* [Conversational](https://docs.tokenfactory.nebius.com/post-training/datasets#conversational-data)
* [Instruction](https://docs.tokenfactory.nebius.com/post-training/datasets#instruction-data)
* [Text](https://docs.tokenfactory.nebius.com/post-training/datasets#text-data)
* [**Pretokenized**](https://docs.tokenfactory.nebius.com/post-training/datasets#pre-tokenized-data)

The size limit for dataset files is **50GB** via Data Lab and 20GB via Files api.

## **Conversational data**

You can train a model using chat-style data. Each training example is a single conversation, represented as one `messages` array.

We \*\*expect the last message to be from the \*\*`assistant`, containing the final answer the model should produce for that conversation.\
\
**Basic example:**

```json theme={null}
{
  "messages": [
    { "role": "system", "content": "You are a friendly dinner planner." },
    { "role": "user", "content": "What's for dinner tonight?" },
    { "role": "assistant", "content": "What cuisine do you prefer?" },
    { "role": "user", "content": "I wouldn't mind Italian." },
    { "role": "assistant", "content": "Then let's try a new pasta!" }
  ]
}
```

Examples of conversational datasets:

* [olathepavilion/Conversational-datasets-json](https://huggingface.co/datasets/olathepavilion/Conversational-datasets-json/blob/main/Validation.jsonl)
* [princefreddy/jsonL\_text\_to\_sql](https://huggingface.co/datasets/princefreddy/jsonL_text_to_sql/blob/main/chatbot_interactions.jsonl)

### Tool-augmented conversations

You can also train the model on conversations that use tools (function calling).

Each training example can optionally include a `tools` field that defines the tools available in that conversation. The schema should match what you plan to use at inference time.

```json theme={null}
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather in a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "messages": [
    { "role": "system", "content": "You are a weather assistant." },
    { "role": "user", "content": "What's the weather in Amsterdam?" },

    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_1",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"Amsterdam\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_1",
      "name": "get_weather",
      "content": "{\"temp_c\": 12, \"condition\": \"cloudy\"}"
    },

    {
      "role": "assistant",
      "content": "It's about 12°C and cloudy in Amsterdam right now."
    }
  ]
}
```

Key points:

* `tools` is **optional**. Omit it for pure conversational data.
* You may include **examples with tool calls** to teach the model:
  * when to call a tool,
  * how to format `tool_calls`,
  * and how to turn tool results into a final answer.
* The \*\*final message in \*\*`messages`\*\*should always be an \*\* `assistant`**message**  with the natural-language answer you want the model to produce (not a tool call).

## **Instruction data**

You can specify prompts and the expected answers to them:

```bash theme={null}
{"prompt": "Capital of Australia", "completion": "Canberra"}
{"prompt": "Distance between Rome and Kuala Lumpur", "completion": "9703 km"}
```

Example of an instruction dataset: [Andzej-75/German\_RisingWorld\_prompt-text-rejected\_Jsonl](https://huggingface.co/datasets/Andzej-75/German_RisingWorld_prompt-text-rejected_Jsonl/blob/main/training_data_Lines.jsonl).

## **Text data**

If you have **unstructured or non-chat data** (tasks, explanations, documents, QA pairs, etc.), you can train using plain text.\
Each training example is a single JSON line with a `text` field.

Example (reasoning-style prompt/answer):

```json theme={null}
{"text": "Given 10 items, find a fair way to divide them among 3 people.\n\n<Answer>: Each person gets 3 items, and 1 item remains. You can rotate who gets the extra item over time to keep it fair."}
{"text": "You are given a list of transactions. Classify whether the account is at risk of fraud.\n\nTransactions: [...]\n\n<Label>: HIGH_RISK"}
```

You can also use this format for longer explanations, documentation-like text, or multi-step solutions:

```json theme={null}
{"text": "Task: Explain how compound interest works to a beginner.\n\nAnswer: Compound interest is interest calculated on the original amount plus any interest that has already been added. This means..."}
```

Example of a text dataset: [FranciscoMacaya/train\_model.jsonl](https://huggingface.co/datasets/FranciscoMacaya/train_model.jsonl/blob/main/train_model.jsonl).

## **Pre-tokenized data**

### When to use pretokenized datasets

Use the **Pretokenized** dataset format if you want to:

* Use a **custom chat template** that differs from the default instruct template.
* Define a **chat template for base models** that don’t have one by default.
* Have full control over **tokenization, packing, loss masking, and attention masking**.

You tokenize everything yourself and upload sequences directly.

### Pretokenized dataset schema

Each sample supports the following fields:

* `input_ids: list[int]` – **required**\
  The Input ID for the full sequence.
* `labels: list[int]` – optional\
  Per-token labels for loss computation.
  * Use `-100` at a position to **mask out loss** for that token (no gradient from that position).
* `attention_mask: list[int]` – optional\
  Segment-aware attention mask and packing layout. The mask must be a **non-decreasing sequence** starting with `1`, with optional trailing `0`s for padding. Valid examples:
  * Single sample (no packing):
    ```text theme={null}
    [1, 1, 1, 1, 1, 1, 1]
    ```
  * Multiple segments packed into one sequence:
    ```text theme={null}
    [1, 1, 2, 2, 3, 3, 3]
    ```
    Here, `1`, `2`, `3` indicate different segments. Our attention implementation **prevents cross-segment attention**, so each segment only attends within itself.
  * Packed segments with padding:
    ```text theme={null}
    [1, 1, 1, 2, 2, 3, 3, 3, 0, 0, 0, 0]
    ```

***

### Using `packing` with pretokenized datasets

You can **combine**:

* `packing = true` (hyperparameter), **and**
* a **Pretokenized** dataset.

In that case:

* Each uploaded sample must have an `attention_mask` of **all ones** (the “single sample” pattern):
  ```text theme={null}
  [1, 1, 1, 1, 1, 1, 1]
  ```
* Nebius will perform the **packing for you** based on `context_length`.

> Note: For some models, `packing = false` is not allowed — those models can only be trained with packing enabled.

### Valid JSONL examples

Each line is one training sample:

```text theme={null}
{"token_ids": [10, 20, 30]}
{"token_ids": [10, 20, 30], "labels": [10, 20, -100]}
{"token_ids": [10, 20, 30], "attention_mask": [1, 1, 1]}
{"token_ids": [10, 20, 30], "labels": [10, 20, -100], "attention_mask": [1, 1, 1]}
```

Constraints to keep in mind:

* `len(token_ids) == len(labels)` (if `labels` provided).
* `len(token_ids) == len(attention_mask)` (if `attention_mask` provided).
* All `token_ids` must be from the **model’s default tokenizer vocabulary** (no custom tokens).

***

## Packing for efficient fine-tuning

When you fine-tune on samples of different lengths, the standard approach is to **pad** all samples in a batch to the longest one. This has two main downsides:

* The **number of tokens per batch fluctuates** a lot between steps.
* That variability leads to **noisier gradients** and can degrade final model quality.

**Packing** fixes this by combining multiple shorter samples into a single sequence while preventing them from interacting with each other.

For typical Transformer architectures, tokens only interact via **attention**. In our implementation, attention is **masked across segments**, so tokens from one segment never attend to tokens from another. Attention is computed independently per segment, but all segments share the same packed sequence.

This gives you:

* Batches with a **more consistent number of training tokens**
* **More stable gradients** and smoother training dynamics
* Better **compute efficiency**, especially when your dataset has many short examples

When packing is enabled, we:

* Combine multiple samples from your dataset into a single sequence of length `context_length`
* Ensure that **no sample is truncated** (neither on the left nor on the right)

> Note: For some large MoE models, packing is **mandatory** and cannot be disabled.

For more background, see:

> *Efficient LLM Pretraining: Packed Sequences and Masked Attention*

If you want to implement your own packing strategy, you can do it client-side and upload the data in the **Pretokenized** dataset format, which supports segments via `attention_mask`.


# Supervised Finetuning 
Source: https://docs.tokenfactory.nebius.com/post-training/how-to-fine-tune

Fine-tune a base model on your own data using Nebius Token Factory. This guide walks you through creating a job, monitoring it, and retrieving checkpoints via API and Python.

***

This guide shows you how to:

* Upload training (and optional validation) datasets
* Create a fine-tuning job via Python or cURL
* Monitor job status and events
* Download the resulting model checkpoints
* Understand the fine-tuning job API shape

***

## Prerequisites

1. Select a supported [**base model**](https://docs.tokenfactory.nebius.com/post-training/models) for **fine-tuning**.
2. [Create a dataset](https://docs.tokenfactory.nebius.com/post-training/datasets) for training.\
   Optionally, create a **validation** dataset as well. A typical split is:
   * **80–90%** of examples → training
   * **10–20%** of examples → validation
3. [Create an API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication).
4. Export the API key as an environment variable:
   ```bash theme={null}
   export NEBIUS_API_KEY=<YOUR_API_KEY>
   ```

***

## How to fine-tune a model

<Tabs>
  <Tab title="Python">
    ### 1. Install and import the client

    1. Install the `openai` Python SDK (Nebius exposes an OpenAI-compatible API):
       ```bash theme={null}
       pip3 install --upgrade openai
       ```
    2. Import libraries:
       ```python theme={null}
       import os
       import time
       from openai import OpenAI
       ```
    3. Initialize the Nebius client:
       ```python theme={null}
       client = OpenAI(
           base_url="https://api.tokenfactory.nebius.com/v1/",
           api_key=os.environ["NEBIUS_API_KEY"],
       )
       ```

    ***

    ### 2. Upload training (and optional validation) datasets

    If you already uploaded datasets via the UI or API, you can skip this and reuse their IDs.

    ```python theme={null}
    # Upload a training dataset
    training_file = client.files.create(
        file=open("training.jsonl", "rb"),
        purpose="fine-tune",
    )

    print("Training file ID:", training_file.id)

    # Optional: upload a validation dataset
    validation_file = client.files.create(
        file=open("validation.jsonl", "rb"),
        purpose="fine-tune",
    )

    print("Validation file ID:", validation_file.id)
    ```

    You only need the `id` fields from these responses to create a fine-tuning job.

    ***

    ### 3. Configure fine-tuning parameters

    For a full list of allowed fields and defaults, see [API specification for a fine-tuning job](#api-specification-for-a-fine-tuning-job).

    ```python theme={null}
    job_request = {
        "model": "meta-llama/Llama-3.1-8B-Instruct",
        "training_file": training_file.id,
        # Optional: only include this if you actually uploaded a validation file
        "validation_file": validation_file.id,
        "suffix": "my-domain-adapter",  # Optional, helps you identify this run
        "hyperparameters": {
            "batch_size": 8,
            "learning_rate": 1e-5,
            "n_epochs": 3,
            "warmup_ratio": 0.0,
            "weight_decay": 0.0,
            "lora": True,
            "lora_r": 16,
            "lora_alpha": 16,
            "lora_dropout": 0.05,
            "packing": True,
            "max_grad_norm": 1.0,
            # context_length is in tokens (e.g. default: 8192)
            "context_length": 8192,
        },
        "seed": 42,
        "integrations": [
            {
                "type": "wandb",
                "wandb": {
                    "project": "my-finetunes",
                    "name": "llama-8b-customer-support",
                    "entity": "my-team",
                    "tags": ["finetune", "llama-3.1", "support-bot"],
                },
            },
            {
                "type": "hf",
                "hf": {
                    "output_repo_name": "<repo>",  # e.g. "org/llama-8b-support-ft"
                    "api_token": "<token-value>",  # HF PAT with write access
                },
            },
        ],
    }
    ```

    ***

    ### 4. Create and run the fine-tuning job

    ```python theme={null}
    job = client.fine_tuning.jobs.create(**job_request)
    print("Created job:", job.id, "status:", job.status)
    ```

    ***

    ### 5. Poll job status

    Fine-tuning takes time. Poll the job until it reaches a terminal status:

    ```python theme={null}
    ACTIVE_STATUSES = ["succeeded", "failed", "cancelled"]
    POLL_INTERVAL_SECONDS = 15

    while job.status in ACTIVE_STATUSES:
        time.sleep(POLL_INTERVAL_SECONDS)
        job = client.fine_tuning.jobs.retrieve(job.id)
        print("Current status:", job.status)

    print("Final status:", job.status)
    print("Job ID:", job.id)

    if job.status == "failed":
        print("Job failed with error:", job.error)
    ```

    * If `job.status == "succeeded"`, training finished successfully.
    * If `job.status == "failed"`, inspect `job.error` for `code`, `message`, and `param`. For transient `5xx` errors, you can safely retry.

    ***

    ### 6. Inspect job events (optional but recommended)

    Events help you understand the lifecycle (file validation, dataset processing, training progress).

    ```python theme={null}
    if job.status == "succeeded":
        events = client.fine_tuning.jobs.list_events(job.id)
        for event in events.data:
            print(event.created_at, event.level, "-", event.message)
    ```

    You can consider training finished when you see messages like:

    * `Dataset processed successfully`
    * `Training completed successfully`

    ***

    ### 7. Download checkpoints and model files

    Each **checkpoint** represents the model after a certain number of training steps (often per epoch).

    ```python theme={null}
    if job.status == "succeeded":
        checkpoints = client.fine_tuning.jobs.checkpoints.list(job.id).data

        for checkpoint in checkpoints:
            print("Checkpoint:", checkpoint.id, "step:", checkpoint.step_number)
            os.makedirs(checkpoint.id, exist_ok=True)

            for file_id in checkpoint.result_files:
                # Get file metadata
                file_obj = client.files.retrieve(file_id)
                filename = file_obj.filename  # e.g. "<checkpoint_ID>/adapter_config.json"

                # Download file contents
                file_content = client.files.content(file_id)

                # Save to disk with the same filename
                output_path = os.path.join(checkpoint.id, os.path.basename(filename))
                file_content.write_to_file(output_path)
                print("Saved:", output_path)
    ```

    You now have:

    * Intermediate checkpoints (per step / epoch)
    * Final checkpoint (usually the last one in the list)

    Use the **latest checkpoint** for deployment unless you have a specific reason to pick an earlier one.

    You can now [deploy your fine-tuned model](https://docs.tokenfactory.nebius.com/post-training/deploy-custom-model#how-to-deploy-a-model-fine-tuned-in-nebius-token-factory) and serve it via Nebius Token Factory.
  </Tab>

  <Tab title="cURL">
    ### 1. Upload datasets

    Upload the **training** dataset:

    ```bash theme={null}
    curl 'https://api.tokenfactory.nebius.com/v1/files' \
      -H 'Accept: application/json' \
      -H 'Content-Type: multipart/form-data' \
      -H "Authorization: Bearer $NEBIUS_API_KEY" \
      -F 'file=@training.jsonl' \
      -F 'purpose=fine-tune'
    ```

    <Accordion title="Response example">
      ```json theme={null}
      {
        "id": "<file_ID>",
        "bytes": 700867,
        "created_at": 1738235422,
        "filename": "training.jsonl",
        "object": "file",
        "purpose": "fine-tune"
      }
      ```
    </Accordion>

    Save the `id` as your `training_file`.

    Optionally, upload a **validation** dataset in the same way and save its `id` as `validation_file`.

    ***

    ### 2. Create a fine-tuning job

    ```bash theme={null}
    curl 'https://api.tokenfactory.nebius.com/v1/fine_tuning/jobs' \
      -X POST \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $NEBIUS_API_KEY" \
      -d '{
        "model": "meta-llama/Llama-3.1-8B-Instruct",
        "suffix": "my-domain-adapter",
        "training_file": "<training_file_ID>",
        "validation_file": "<validation_file_ID>",
        "hyperparameters": {
          "batch_size": 8,
          "learning_rate": 0.00001,
          "n_epochs": 3,
          "warmup_ratio": 0.0,
          "weight_decay": 0.0,
          "lora": true,
          "lora_r": 16,
          "lora_alpha": 16,
          "lora_dropout": 0.05,
          "packing": true,
          "max_grad_norm": 1.0,
          "context_length": 8192
        },
        "seed": 42,
        "integrations": [
          {
            "type": "wandb",
            "wandb": {
              "project": "my-finetunes",
              "name": "llama-8b-customer-support",
              "entity": "my-team",
              "tags": ["finetune", "llama-3.1", "support-bot"]
            }
          }
        ]
      }'
    ```

    You can now [deploy the produced model files](https://docs.tokenfactory.nebius.com/fine-tuning/deploy-custom-model#how-to-deploy-a-model-fine-tuned-in-nebius-token-factory) when the job succeeds.

    ***

    ### 3. Check job status

    ```bash theme={null}
    curl "https://api.tokenfactory.nebius.com/v1/fine_tuning/jobs/<job_ID>" \
      -X GET \
      -H "Accept: application/json" \
      -H "Authorization: Bearer $NEBIUS_API_KEY"
    ```

    <Accordion title="200 OK response example">
      ```json theme={null}
      {
        "id": "<job_ID>",
        "created_at": 1738250578,
        "error": null,
        "finished_at": null,
        "hyperparameters": {
          "batch_size": 8,
          "learning_rate": 0.00001,
          "n_epochs": 3,
          "warmup_ratio": 0,
          "weight_decay": 0,
          "lora": true,
          "lora_r": 16,
          "lora_alpha": 16,
          "lora_dropout": 0.05,
          "packing": true,
          "max_grad_norm": 1,
          "context_length": 8192
        },
        "model": "<model_name>",
        "object": "fine_tuning.job",
        "organization_id": "",
        "result_files": [],
        "seed": 0,
        "status": "running",
        "trained_tokens": 0,
        "training_file": "<file_ID>",
        "validation_file": "<file_ID>",
        "estimated_finish": null,
        "suffix": "",
        "trained_steps": 0,
        "total_steps": 100
      }
      ```
    </Accordion>

    * Poll this endpoint every **≥ 15 seconds**.
    * Terminal statuses: `succeeded`, `failed`.
    * If `status` is `failed`, inspect the `error` object. For transient server errors (`5xx`), you can recreate the job.

    ***

    ### 4. Inspect job events

    ```bash theme={null}
    curl "https://api.tokenfactory.nebius.com/v1/fine_tuning/jobs/<job_ID>/events" \
      -X GET \
      -H "Accept: application/json" \
      -H "Authorization: Bearer $NEBIUS_API_KEY" \
      --url-query limit=50
    ```

    Supported query parameters:

    * `limit` (integer, optional): Max number of events to return.
    * `after` (string, optional): Event ID to paginate after.

    You can consider training completed when you see messages like:

    * `Dataset '<file_ID>' processed successfully`
    * `Training completed successfully`

    <Accordion title="200 OK response example">
      ```json theme={null}
      {
        "data": [
          {
            "object": "fine_tuning.job.event",
            "id": "<event_ID>",
            "created_at": 1738250578,
            "level": "info",
            "message": "Job is submitted",
            "source": "api",
            "job_uuid": "<job_ID>"
          },
          {
            "object": "fine_tuning.job.event",
            "id": "<event_ID>",
            "created_at": 1738250609,
            "level": "info",
            "message": "Dataset '<file_ID>' processed successfully",
            "source": "datasets",
            "job_uuid": "<job_ID>"
          }
        ],
        "has_more": false
      }
      ```
    </Accordion>

    ***

    ### 5. List checkpoints

    ```bash theme={null}
    curl "https://api.tokenfactory.nebius.com/v1/fine_tuning/jobs/<job_ID>/checkpoints" \
      -X GET \
      -H "Accept: application/json" \
      -H "Authorization: Bearer $NEBIUS_API_KEY"
    ```

    <Accordion title="200 OK response example">
      ```json theme={null}
      {
        "object": "list",
        "data": [
          {
            "id": "<checkpoint_ID>",
            "created_at": 1740501233,
            "fine_tuned_model_checkpoint": "ft:meta-llama/Llama-3.1-8B-Instruct-2025-02-25:org_placeholder::IDPlaceholder:ckpt-step-3",
            "fine_tuning_job_id": "<job_ID>",
            "metrics": {
              "train_loss": 2.01,
              "valid_loss": 2.32
            },
            "object": "fine_tuning.job.checkpoint",
            "step_number": 3,
            "result_files": [
              "<file_ID_1>",
              "<file_ID_2>",
              "<file_ID_3>"
            ]
          }
        ],
        "first_id": "<first_checkpoint_ID>",
        "last_id": "<last_checkpoint_ID>",
        "has_more": false
      }
      ```
    </Accordion>

    The `result_files` array contains IDs of all files that belong to this checkpoint.

    ***

    ### 6. Inspect file metadata

    ```bash theme={null}
    curl "https://api.tokenfactory.nebius.com/v1/files/<file_ID>" \
      -X GET \
      -H "Accept: application/json" \
      -H "Authorization: Bearer $NEBIUS_API_KEY"
    ```

    <Accordion title="200 OK response example">
      ```json theme={null}
      {
        "id": "<file_ID>",
        "bytes": 907,
        "created_at": 1740501244,
        "filename": "<checkpoint_ID>/adapter_config.json",
        "object": "file",
        "purpose": "fine-tune"
      }
      ```
    </Accordion>

    Use the `filename` field to save the file with the correct path and extension.

    ***

    ### 7. Download file contents

    ```bash theme={null}
    curl "https://api.tokenfactory.nebius.com/v1/files/<file_ID>/content" \
      -X GET \
      -H "Accept: application/json" \
      -H "Authorization: Bearer $NEBIUS_API_KEY"
    ```

    Copy the content from the response and save it locally with the name from the `filename` field you retrieved in the previous step.

    Once you download the required checkpoint files, you can [host the fine-tuned model](https://docs.tokenfactory.nebius.com/fine-tuning/deploy-custom-model#how-to-deploy-a-model-fine-tuned-in-nebius-token-factory) and serve it via Nebius Token Factory.
  </Tab>
</Tabs>

***

## API specification for a fine-tuning job

This section describes the **request payload** when creating a fine-tuning job.

```json theme={null}
{
  "model": "<string>",
  "suffix": "<string>",
  "training_file": "<file_ID>",
  "validation_file": "<file_ID>",
  "hyperparameters": {
    "batch_size": 8,
    "learning_rate": 0.00001,
    "n_epochs": 3,
    "warmup_ratio": 0,
    "weight_decay": 0,
    "lora": false,
    "lora_r": 8,
    "lora_alpha": 8,
    "lora_dropout": 0,
    "packing": true,
    "max_grad_norm": 1,
    "context_length": 8192
  },
  "seed": 42,
   "integrations": [
    {
      "type": "wandb",
      "wandb": {
        "project": "<string>",
        "name": "<string>",
        "entity": "<string>",
        "tags": ["<string>"]
      }
    },
    {
      "type": "hf",
      "hf": {
        "output_repo_name": "<string>", 
        "api_token": "<string>"
      }
    }
  ]
}
```

### Top-level fields

* `model` (string, **required**) Base [model](https://docs.tokenfactory.nebius.com/post-training/models) to fine-tune.
* `suffix` (string, optional) Human-readable suffix appended to the model name. Use this to distinguish multiple runs, e.g., `customer-support-v1`.
* `training_file` (string, **required**) ID of the file with the training dataset (`purpose = "fine-tune"`). See:
  * [How to create a dataset for fine-tuning](https://docs.tokenfactory.nebius.com/post-training/datasets)
  * [How to fine-tune a model](https://docs.tokenfactory.nebius.com/post-training/how-to-fine-tune)
* `validation_file` (string, optional) ID of the file with the validation dataset. Same format and requirements as the training dataset.
* `hyperparameters` (object, optional) Fine-tuning configuration. Omitted fields fall back to defaults.
* `seed` (integer, optional) Random seed used during training. Using the same `seed` and the same data/hyperparameters improves reproducibility between runs.
* `integrations` (array, optional) Third-party integrations configured for this job.
  * `type` (string, required) Currently supported: `"wandb"`.
* `wandb` (object, required when `type = "wandb"`) Settings for exporting metrics to \
  \
  [Weights & Biases](https://wandb.ai/):
  * `project` (string, required): W\&B project name.
  * `name` (string, optional): Run name.
  * `entity` (string, optional): W\&B entity (user or team).
  * `tags` (array of strings, optional): Tags to attach to the run. [**Hugging Face integration**](https://huggingface.co/): **hf** (object, required when `type = "hf"`)
  * `output_repo_name` (string, required):\
    Target Hugging Face repo name, e.g. `"org/llama-8b-support-ft"` or `"username/my-finetune"`.
  * `api_token` (string, required):\
    Hugging Face access token (PAT) with write access to `output_repo_name`.

***

### Hyperparameters

All hyperparameters are nested under `hyperparameters`.

* `batch_size` (integer, optional) Number of examples per training batch. Larger batch sizes are more efficient but require more VRAM.
  * Typical range: `8`–`32`
  * Default: `8`
* `context_length` (integer, optional) Maximum sequence length in tokens used during fine-tuning. Inputs longer than this limit will cause errors.
  * Units: tokens (e.g., `8192`)
  * Supported values depend on the base model; see the [models](https://docs.tokenfactory.nebius.com/fine-tuning/models) page.
  * Default: `8192` We recommend:
  * Analyze the token length distribution of your dataset.
  * Choose the smallest context length that covers your P95–P99 examples.
  * If `packing = false`, a much larger context length choice than your examples leads to heavy padding and wasted compute.
  <Tip>
    Larger context lengths significantly increase VRAM usage and FLOPs due to attention scaling.
  </Tip>
* `learning_rate` (float, optional) Step size for gradient descent.
  * Must be `>= 0`
  * Typical values: `1e-6`–`5e-5`
  * Default: `0.00001`
* `n_epochs` (integer, optional) Number of passes over the entire dataset.
  * Range: `1`–`20`
  * Default: `3` More epochs increase task specialization but also overfitting risk.
* `warmup_ratio` (float, optional) Fraction of total training steps used for linear warmup of the learning rate from 0 to the target value.
  * Range: `0`–`1`
  * Default: `0`
* `weight_decay` (float, optional) L2 regularization factor applied to weights. Helps prevent overfitting and preserve generalization.
  * Must be `>= 0`
  * Default: `0`
* `lora` (boolean, optional) Whether to use **LoRA** (Low-Rank Adaptation) instead of full-parameter fine-tuning.
  * `true`: only LoRA adapter weights are trained; base model weights stay frozen.
  * `false`: full fine-tuning is applied.
  * Default: `false`
* `lora_r` (integer, optional) Rank of LoRA matrices. Higher values increase capacity but also overfitting and cost.
  * Range: `8`–`128`
  * Default: `8`
* `lora_alpha` (integer, optional) Scaling factor for LoRA updates. Higher values increase the impact of LoRA adapters.
  * Must be `>= 8`
  * Default: `8`
* `lora_dropout` (float, optional) Dropout applied to LoRA layers. Helps prevent overfitting, especially on small datasets.
  * Range: `0`–`1`
  * Default: `0`
* `packing` (boolean, optional) If `true`, multiple shorter samples can be packed into a single sequence to better utilize the context window and improve efficiency.
  * Default: `true`
* `max_grad_norm` (float, optional) Gradient clipping threshold (L2 norm). Avoids unstable updates:
  * Too **high** → effectively no clipping → risk of **exploding gradients**.
  * Too **low** → overly aggressive clipping → risk of **under-training**.
  * Must be `>= 0`
  * Default: `1`

***

### Fine-tuning job object (response shape)

When you query a job or list jobs, you get objects shaped like this:

```json theme={null}
{
  "data": [
    {
      "id": "<string>",
      "created_at": 123,
      "hyperparameters": {
        "batch_size": 8,
        "learning_rate": 0.00001,
        "n_epochs": 3,
        "warmup_ratio": 0,
        "weight_decay": 0,
        "lora": false,
        "lora_r": 8,
        "lora_alpha": 8,
        "lora_dropout": 0,
        "packing": true,
        "max_grad_norm": 1,
        "context_length": 8192
      },
      "model": "<string>",
      "status": "validating_files",
      "training_file": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>",
        "param": "<string>"
      },
      "finished_at": 123,
     "integrations": [
        {
          "wandb": {
            "project": "<string>",
            "name": "<string>",
            "entity": "<string>",
            "tags": ["<string>"]
          },
          "type": "wandb"
        },
        {
          "hf": {
            "output_repo_name": "<string>",
            "api_token": "<string>"
          },
          "type": "hf"
        }
      ],
      "object": "fine_tuning.job",
      "organization_id": "",
      "result_files": [],
      "seed": 0,
      "suffix": "<string>",
      "trained_tokens": 123,
      "validation_file": "<string>",
      "estimated_finish": 123,
      "trained_steps": 123,
      "total_steps": 123
    }
  ],
  "has_more": true,
  "object": "list"
}
```

Key fields to watch during a run:

* `status`: `validating_files` → `queued` → `running` → `succeeded` / `failed`
* `trained_tokens`: how many tokens have been processed so far
* `trained_steps` / `total_steps`: progress of the training loop
* `error`: structured error info when `status = "failed"`
* `result_files`: IDs of produced artifacts (also available via checkpoints API)

Use these fields plus job events to drive your own monitoring, dashboards, or CI/CD automation around fine-tuning.


# Merging LoRA Adapters
Source: https://docs.tokenfactory.nebius.com/post-training/merge-moe-lora-weights

When you fine-tune a model with LoRA, inference usually requires loading both the base model and the LoRA adapter. Here we provide a merge script that bakes the LoRA adapters directly into the base weights and produces a standard checkpoint directory.

This guide explains how to:

* Install requirements
* Download base and LoRA checkpoints
* Run the merge script
* Use the merged model with vLLM

***

### 1. Install dependencies

```text theme={null}
pip install safetensors huggingface_hub transformers peft
```

These are required for:

* loading safetensors checkpoints
* reading LoRA configs
* downloading models from Hugging Face

***

### 2. Download the base model checkpoint

You must use **the exact same base model** that was used during LoRA training.

Example (Hugging Face Hub):

```text theme={null}
hf download unsloth/gpt-oss-20b-BF16 --local-dir gpt-oss-20b-BF16
```

This gives you a directory like:

```text theme={null}
gpt-oss-20b-BF16/
  ├─ model-00001-of-000xx.safetensors
  ├─ model-00002-of-000xx.safetensors
  ├─ config.json
  ├─ tokenizer.json
  └─ ...
```

You’ll pass this as:

* `--orig_ckpt_path gpt-oss-20b-BF16`

***

### 3. Download the LoRA checkpoint

Download the LoRA adapter either from the UI or via CLI into a directory, for example:

```text theme={null}
my-lora-adapter/
  ├─ adapter_model.safetensors
  ├─ adapter_config.json
  └─ ...
```

You’ll pass this as:

* `--lora_ckpt_path my-lora-adapter`

***

### 4. Save the merge script

Create a file named `merge_lora.py` and paste the following:

```python theme={null}
"""
Script to merge lora weights into base model


---

# Instruction

1. Do not forget to install dependencies:
> pip install safetensors huggingface_hub transformers peft

2. Download lora weights from UI or via cli

3. Initial weights must be the same as specified by the lora adapter
    In order to obtain initial weights, you can run:
> hf download unsloth/gpt-oss-20b-BF16 --local-dir gpt-oss-20b-BF16'
Now you can specify it via `--orig_ckpt_path gpt-oss-20b-BF16`

4. Run conversion
> python merge_weights.py -i <base-ckpt> -l <lora-ckpt> -o <merged-weighs-ckpt>
"""

import argparse
import re
import shutil
from pathlib import Path

import torch
from peft import LoraConfig
from safetensors import safe_open
from safetensors.torch import save_file


ALLOWED_LORA_LAYERS = [
    r"model.layers.*.self_attn",
]


def _compile_patterns(patterns: list[str]) -> list[re.Pattern]:
    compiled = []
    for p in patterns:
        esc = re.escape(p).replace(r"\*", ".*")
        regex = r"^" + esc + r"(?:\..*)?$"
        compiled.append(re.compile(regex))
    return compiled


INCLUDE_PATTERNS = _compile_patterns(ALLOWED_LORA_LAYERS)


def _needs_lora_merge(key: str) -> bool:
    return any(p.match(key) for p in INCLUDE_PATTERNS)


def _merge_lora_weight(
    tensor_name: str,
    tensor: torch.Tensor,
    lora_weights: dict[str, torch.Tensor],
    lora_config: LoraConfig,
) -> torch.Tensor:
    scale = lora_config.lora_alpha / lora_config.r
    tensor_prefix = tensor_name.rsplit(".", 1)[0]  # remove .weight
    A_name, B_name = f"{tensor_prefix}.lora_A.weight", f"{tensor_prefix}.lora_B.weight"
    A, B = (
        lora_weights[A_name],
        lora_weights[B_name],
    )
    deltaW = B @ A
    merged_weight = tensor + scale * deltaW

    del lora_weights[A_name]
    del lora_weights[B_name]
    print(f"Merged layer {tensor_name}")
    return merged_weight


def _process_single_file(
    safetensors_path: Path,
    lora_config: LoraConfig,
    lora_weights: dict[str, torch.Tensor],
    output_ckpt_path: Path,
):
    safetensors = {}
    with safe_open(safetensors_path, framework="torch") as f:
        for tensor_name in f.keys():
            tensor = f.get_tensor(tensor_name)
            if _needs_lora_merge(tensor_name) and tensor_name.endswith(".weight"):
                tensor = _merge_lora_weight(
                    tensor_name,
                    tensor,
                    lora_weights,
                    lora_config,
                )
            safetensors[tensor_name] = tensor

    output_path = output_ckpt_path / safetensors_path.name
    save_file(safetensors, filename=output_path)
    print(f"Merged and unloaded safetensor {output_path}")


def merge_lora_weights(
    orig_ckpt_path: Path | str,
    lora_ckpt_path: Path | str,
    output_ckpt_path: Path | str,
):
    orig_ckpt_path = Path(orig_ckpt_path)
    lora_ckpt_path = Path(lora_ckpt_path)
    output_ckpt_path = Path(output_ckpt_path)
    output_ckpt_path.mkdir(exist_ok=True, parents=True)

    torch.manual_seed(42)
    #torch.cuda.manual_seed(42) #enable this if CUDA available 

    lora_config = LoraConfig.from_pretrained(lora_ckpt_path)
    lora_weights = {}
    with safe_open(
        lora_ckpt_path / "adapter_model.safetensors", framework="torch"
    ) as f:
        for tensor_name in f.keys():
            if not _needs_lora_merge(tensor_name):
                raise ValueError("Provided layer-pattern is not listed as ALLOWED")
            tensor = f.get_tensor(tensor_name)
            lora_weights[tensor_name] = tensor

    safetensor_paths = list(orig_ckpt_path.glob("*.safetensors"))

    for path in safetensor_paths:
        _process_single_file(path, lora_config, lora_weights, output_ckpt_path)

    if len(lora_weights) != 0:
        raise ValueError(f"Found non-merged lora weights: {lora_weights.keys()}")

    for path in set(orig_ckpt_path.glob("*")) - set(
        orig_ckpt_path.glob("*.safetensors")
    ):
        shutil.copy(path, output_ckpt_path / path.name)
    print("Copied the rest of the files")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Merge LoRA weights into main weights")
    parser.add_argument(
        "-i",
        "--orig_ckpt_path",
        type=str,
        required=True,
        help="Path to the original checkpoint directory containing safetensors files",
    )
    parser.add_argument(
        "-l",
        "--lora_ckpt_path",
        type=str,
        required=True,
        help="Path to the output converted checkpoint directory",
    )
    parser.add_argument(
        "-o",
        "--output_ckpt_path",
        type=str,
        required=True,
        help="Path to save merged checkpoint",
    )
    args = parser.parse_args()

    merge_lora_weights(
        orig_ckpt_path=args.orig_ckpt_path,
        lora_ckpt_path=args.lora_ckpt_path,
        output_ckpt_path=args.output_ckpt_path,
    )
```

> **Important:**\
> `--lora_ckpt_path` must point to the **LoRA adapter directory** that contains `adapter_model.safetensors` (and `adapter_config.json`), not to the base model.

***

### 5. Run the merge

Example:

```text theme={null}
python merge_lora.py \
  --orig_ckpt_path gpt-oss-20b-BF16 \
  --lora_ckpt_path my-lora-adapter \
  --output_ckpt_path gpt-oss-20b-BF16-lora-merged
```

After it completes, you’ll have:

```text theme={null}
gpt-oss-20b-BF16-lora-merged/
  ├─ model-00001-of-000xx.safetensors   # now includes LoRA deltas
  ├─ model-00002-of-000xx.safetensors
  ├─ config.json
  ├─ tokenizer.json
  └─ ...
```

All non-`.safetensors` files are copied from the original checkpoint directory.

***

### Notes & constraints

* By default, only layers matching:
  ```text theme={null}
  ALLOWED_LORA_LAYERS = [
      r"model.layers.*.self_attn",
  ]
  ```
  are merged. If you trained LoRA on other modules (e.g. MLPs), extend `ALLOWED_LORA_LAYERS` accordingly.
* The script will fail if:
  * The LoRA weights are not compatible with the base checkpoint
  * Some LoRA weights remain unused (non-merged) after processing all shards

This keeps merges explicit and avoids silently ignoring parts of the adapter.


# Models for fine-tuning in Nebius Token Factory
Source: https://docs.tokenfactory.nebius.com/post-training/models

Supported base models for fine-tuning in Nebius Token Factory, with available context lengths and fine-tuning types (LoRA and full fine-tuning), grouped by provider.

Nebius Token Factory supports fine-tuning on multiple open-weight model families.<br />This page lists:

* Which **base models** you can fine-tune
* Which **context lengths** they support
* Which **fine-tuning types** are available (LoRA vs full fine-tuning)

***

## Model List

For each models listed below, Nebius Token Factory supports the following <br /><br />`context_length: 8192`, `16384`, `32768`, `65536`, `131072`

Unless you override it via the `context_length` hyperparameter, the default context length for fine-tuning is **8192 tokens**.

Check hyperparameter section for model details regarding `context_length`

***

## DeepSeek

Nebius Token Factory integrates DeepSeek V3 and V4 models for high-capacity reasoning workloads.<br />DeepSeek and its variants are released under the **MIT License** (see model cards for details).

| Name                                                                                                    | Supported fine-tuning type | Model card / license                                                                  |
| :------------------------------------------------------------------------------------------------------ | :------------------------- | :------------------------------------------------------------------------------------ |
| deepseek-ai/DeepSeek-V3-0324<br />([Model card](https://huggingface.co/deepseek-ai/DeepSeek-V3-0324))   | Full fine-tuning           | [MIT License](https://huggingface.co/deepseek-ai/DeepSeek-V3-0324/blob/main/LICENSE)  |
| deepseek-ai/DeepSeek-V4-Flash<br />([Model card)](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash) | Full fine-tuning           | [MIT License](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash/blob/main/LICENSE) |

***

## Google

Nebius Token Factory supports full fine-tuning for select Google Gemma 4 instruction-tuned models.

These models are available under the Apache 2.0 License. Review the corresponding model card for full license terms and usage details.

| Name                                                                                    | Supported fine-tuning type | License                                                       |
| :-------------------------------------------------------------------------------------- | :------------------------- | :------------------------------------------------------------ |
| google/gemma-4-E2B-it<br />([Model card](https://huggingface.co/google/gemma-4-E2B-it)) | Full fine-tuning           | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| google/gemma-4-E4B-it<br />([Model card)](https://huggingface.co/google/gemma-4-E4B-it) | Full fine-tuning           | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| google/gemma-4-31B-it<br />[(Model card)](https://huggingface.co/google/gemma-4-31B-it) | Full fine-tuning           | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |

***

## OpenAI / Unsloth GPT-OSS

These models are OpenAI GPT-OSS weights (bf16) packaged by Unsloth.<br />They are Apache 2.0–licensed and suitable for both research and commercial use (subject to the license).

To convert the weights into MXFP4 please follow instructions [here](https://docs.tokenfactory.nebius.com/post-training/weights-conversion).

| Name                                                                                            | Training type                       | License                                                       |
| :---------------------------------------------------------------------------------------------- | :---------------------------------- | :------------------------------------------------------------ |
| unsloth/gpt-oss-20b-BF16<br />([Model card](https://huggingface.co/unsloth/gpt-oss-20b-BF16))   | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| unsloth/gpt-oss-120b-BF16<br />([Model card](https://huggingface.co/unsloth/gpt-oss-120b-BF16)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |

<Note>
  For merging MoE LoRA adapter weights to deploy on Dedicated endpoints please follow the guide [here](https://docs.tokenfactory.nebius.com/post-training/merge-moe-lora-weights).
</Note>

***

## Qwen

Nebius Token Factory supports **dense, moe** and **coder** variants across Qwen3 and Qwen2.5 families.<br />All Qwen models below use the **Apache 2.0** license (see each model card for details).

### Qwen3 MoE

| Name                                                                                                              | Training type                       | License                                                                                   |
| :---------------------------------------------------------------------------------------------------------------- | :---------------------------------- | :---------------------------------------------------------------------------------------- |
| Qwen/Qwen3-235B-A22B<br />([Model card](https://huggingface.co/Qwen/Qwen3-235B-A22B))                             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-235B-A22B/blob/main/LICENSE)               |
| Qwen/Qwen3-235B-A22B-Instruct-2507<br />([Model card](https://huggingface.co/Qwen/Qwen3-235B-A22B-Instruct-2507)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-235B-A22B-Instruct-2507/blob/main/LICENSE) |
| Qwen/Qwen3-235B-A22B-Thinking-2507<br />([Model card](https://huggingface.co/Qwen/Qwen3-235B-A22B-Thinking-2507)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-235B-A22B-Thinking-2507/blob/main/LICENSE) |
| Qwen/Qwen3-30B-A3B<br />([Model card](https://huggingface.co/Qwen/Qwen3-30B-A3B))                                 | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-30B-A3B/blob/main/LICENSE)                 |
| Qwen/Qwen3-30B-A3B-Instruct-2507<br />([Model card](https://huggingface.co/Qwen/Qwen3-30B-A3B-Instruct-2507))     | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-30B-A3B-Instruct-2507/blob/main/LICENSE)   |
| Qwen/Qwen3-30B-A3B-Thinking-2507<br />([Model card](https://huggingface.co/Qwen/Qwen3-30B-A3B-Thinking-2507))     | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-30B-A3B-Thinking-2507/blob/main/LICENSE)   |

### Qwen3 coder

| Name                                                                                                                | Training type                       | License                                                                                    |
| :------------------------------------------------------------------------------------------------------------------ | :---------------------------------- | :----------------------------------------------------------------------------------------- |
| Qwen/Qwen3-Coder-30B-A3B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct))     | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct/blob/main/LICENSE)   |
| Qwen/Qwen3-Coder-480B-A35B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen3-Coder-480B-A35B-Instruct)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://huggingface.co/Qwen/Qwen3-Coder-480B-A35B-Instruct/blob/main/LICENSE) |

### Qwen3 dense + base

| Name                                                                                  | Training type                       | License                                                       |
| :------------------------------------------------------------------------------------ | ----------------------------------- | :------------------------------------------------------------ |
| Qwen/Qwen3-32B<br />([Model card](https://huggingface.co/Qwen/Qwen3-32B))             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-14B<br />([Model card](https://huggingface.co/Qwen/Qwen3-14B))             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-14B-Base<br />([Model card](https://huggingface.co/Qwen/Qwen3-14B-Base))   | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-8B<br />([Model card](https://huggingface.co/Qwen/Qwen3-8B))               | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-8B-Base<br />([Model card](https://huggingface.co/Qwen/Qwen3-8B-Base))     | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-4B<br />([Model card](https://huggingface.co/Qwen/Qwen3-4B))               | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-4B-Base<br />([Model card](https://huggingface.co/Qwen/Qwen3-4B-Base))     | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-1.7B<br />([Model card](https://huggingface.co/Qwen/Qwen3-1.7B))           | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-1.7B-Base<br />([Model card](https://huggingface.co/Qwen/Qwen3-1.7B-Base)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-0.6B<br />([Model card](https://huggingface.co/Qwen/Qwen3-0.6B))           | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen3-0.6B-Base<br />([Model card](https://huggingface.co/Qwen/Qwen3-0.6B-Base)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |

### Qwen3.5

| Name                                                                          | Training type              | License                                                       |
| :---------------------------------------------------------------------------- | :------------------------- | :------------------------------------------------------------ |
| Qwen/Qwen3.5-27B<br />[(Model card)](https://huggingface.co/Qwen/Qwen3.5-27B) | Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |

### Qwen3.6

| Name                                                                          | Training type              | License                                                       |
| :---------------------------------------------------------------------------- | :------------------------- | :------------------------------------------------------------ |
| Qwen/Qwen3.6-27B<br />[(Model card)](https://huggingface.co/Qwen/Qwen3.6-27B) | Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |

### Qwen2.5 dense + coder

| Name                                                                                                        | Training type                       | License                                                       |
| :---------------------------------------------------------------------------------------------------------- | :---------------------------------- | :------------------------------------------------------------ |
| Qwen/Qwen2.5-0.5B<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-0.5B))                             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-0.5B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct))           | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-7B<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-7B))                                 | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-7B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct))               | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-14B<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-14B))                               | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-14B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-14B-Instruct))             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-32B<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-32B))                               | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-32B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-32B-Instruct))             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-72B<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-72B))                               | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-72B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct))             | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-Coder-32B<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-Coder-32B))                   | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |
| Qwen/Qwen2.5-Coder-32B-Instruct<br />([Model card](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct)) | LoRA and Full Parameter fine-tuning | [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) |

***

## Meta (Llama 3.1 / 3.2 / 3.3)

Nebius Token Factory and the Meta models hosted in the service are built on the **Llama 3.1**, **Llama 3.2**, and **Llama 3.3** families.

For acceptable use, see Meta’s policies:

* [Llama 3.1 Acceptable Use Policy](https://llama.meta.com/llama3_1/use-policy/)
* [Llama 3.2 Acceptable Use Policy](https://www.llama.com/llama3_2/use-policy/)
* [Llama 3.3 Acceptable Use Policy](https://www.llama.com/llama3_3/use-policy/)

| Name                                                                                                                    | Training type                       | License                                                                                                               |
| :---------------------------------------------------------------------------------------------------------------------- | :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| meta-llama/Meta-Llama-3.1-8B-Instruct<br />([Model card](https://huggingface.co/meta-llama/Meta-Llama-3.1-8B-Instruct)) | LoRA and Full Parameter fine-tuning | [Llama 3.1 Community License Agreement](https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/LICENSE) |
| meta-llama/Meta-Llama-3.1-8B<br />([Model card](https://huggingface.co/meta-llama/Llama-3.1-8B))                        | LoRA and Full Parameter fine-tuning | [Llama 3.1 Community License Agreement](https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/LICENSE) |
| meta-llama/Llama-3.1-70B-Instruct<br />([Model card](https://huggingface.co/meta-llama/Llama-3.1-70B-Instruct))         | LoRA and Full Parameter fine-tuning | [Llama 3.1 Community License Agreement](https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/LICENSE) |
| meta-llama/Llama-3.1-70B<br />([Model card](https://huggingface.co/meta-llama/Llama-3.1-70B))                           | LoRA and Full Parameter fine-tuning | [Llama 3.1 Community License Agreement](https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/LICENSE) |
| meta-llama/Llama-3.2-1B-Instruct<br />([Model card](https://huggingface.co/meta-llama/Llama-3.2-1B-Instruct))           | LoRA and Full Parameter fine-tuning | [Llama 3.2 Community License Agreement](https://huggingface.co/meta-llama/Llama-3.2-1B/blob/main/LICENSE.txt)         |
| meta-llama/Llama-3.2-1B<br />([Model card](https://huggingface.co/meta-llama/Llama-3.2-1B))                             | LoRA and Full Parameter fine-tuning | [Llama 3.2 Community License Agreement](https://huggingface.co/meta-llama/Llama-3.2-1B/blob/main/LICENSE.txt)         |
| meta-llama/Llama-3.2-3B-Instruct<br />([Model card](https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct))           | LoRA and Full Parameter fine-tuning | [Llama 3.2 Community License Agreement](https://huggingface.co/meta-llama/Llama-3.2-3B/blob/main/LICENSE.txt)         |
| meta-llama/Llama-3.2-3B<br />([Model card](https://huggingface.co/meta-llama/Llama-3.2-3B))                             | LoRA and Full Parameter fine-tuning | [Llama 3.2 Community License Agreement](https://huggingface.co/meta-llama/Llama-3.2-3B/blob/main/LICENSE.txt)         |
| meta-llama/Llama-3.3-70B-Instruct<br />([Model card](https://huggingface.co/meta-llama/Llama-3.3-70B-Instruct))         | LoRA and Full Parameter fine-tuning | [Llama 3.3 Community License Agreement](https://github.com/meta-llama/llama-models/blob/main/models/llama3_3/LICENSE) |

Deployment options currently only include via Dedicated endpoints.


# Overview
Source: https://docs.tokenfactory.nebius.com/post-training/overview

Post-training on Nebius Token Factory

Post-training in **Nebius Token Factory** lets you adapt foundation models to your data and tasks. By training on your own examples, the model learns your domain patterns directly improving accuracy, stability, and reducing prompt complexity.

[**Supervised fine-tuning**](https://docs.tokenfactory.nebius.com/post-training/how-to-fine-tune) allows you to train on large datasets without prompt-length limits. This gives you tighter control over model behavior, reduces the need for manual prompt engineering, and can lead to lower inference cost and latency.

[**Custom speculator training**](https://docs.tokenfactory.nebius.com/post-training/custom-speculator) allows you to train a drafter tuned to your own base model and workload, rather than relying on a generic speculator. This gives you higher inference throughput and lower latency during speculative decoding, driven by better token acceptance rates, while preserving the base model's output quality.<br /><br />Upcoming Advanced post-training options including:

* **Reinforcement Fine-tuning** (limited professional service [request access](https://nebius.com/reinforcement-fine-tuning-research-program))

<Note>
  You can currently run **long-context supervised fine-tuning** on full model weights or **LoRA adapters**.
</Note>

If you're ready to fine-tune or want to explore the workflows involved, start here:

<Columns>
  <Card title="How to Fine-tune" icon="layer-group" href="https://docs.tokenfactory.nebius.com/post-training/how-to-fine-tune">
    Step-by-step guide to preparing data, launching a job, and evaluating results.
  </Card>

  <Card title="Models" icon="list" href="https://docs.tokenfactory.nebius.com/post-training/models">
    Supported base models for training and inference.
  </Card>

  <Card title="Datasets" icon="table" href="https://docs.tokenfactory.nebius.com/post-training/datasets">
    Create and manage datasets for training and validation.
  </Card>
</Columns>

***


# Quickstart
Source: https://docs.tokenfactory.nebius.com/quickstart

Welcome to Nebius Token Factory

## Start building now

<CodeGroup>
  ```python Python expandable theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.tokenfactory.nebius.com/v1/",
      api_key=os.environ.get("NEBIUS_API_KEY")
  )

  response = client.chat.completions.create(
      model="deepseek-ai/DeepSeek-R1-0528",
      messages=[
          {
              "role": "system",
              "content": """You are a helpful assistant"""
          },
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": """hello"""
                  }
              ]
          }
      ]
  )

  print(response.to_json())
  ```

  ```javascript JavaScript expandable theme={null}
  const OpenAI = require('openai');

  const client = new OpenAI({
      baseURL: 'https://api.tokenfactory.nebius.com/v1/',
      apiKey: process.env.NEBIUS_API_KEY,
  });

  client.chat.completions.create({
      "model": "deepseek-ai/DeepSeek-R1-0528",
      "messages": [
          {
              "role": "system",
              "content": "You are a helpful assistant"
          },
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": "hello"
                  }
              ]
          }
      ]
  })
      .then((response) => console.log(response));
  ```

  ```bash cURL expandable theme={null}
  curl 'https://api.tokenfactory.nebius.com/v1/chat/completions' \
      -X 'POST' \
      -H 'Content-Type: application/json' \
      -H 'Accept: */*' \
      -H "Authorization: Bearer $NEBIUS_API_KEY" \
      --data-binary '{"model":"deepseek-ai/DeepSeek-R1-0528","messages":[{"role":"system","content":"You are a helpful assistant"},{"role":"user","content":[{"type":"text","text":"hello"}]}]}'
  ```
</CodeGroup>

<AccordionGroup>
  <Accordion title="Get API key" icon="key">
    1. Go to [https://tokenfactory.nebius.com](https://tokenfactory.nebius.com/), create an account
    2. Log in using your Google or GitHub account
    3. For authentication, [get an API key](https://docs.tokenfactory.nebius.com/api-reference/introduction#authentication)
  </Accordion>

  <Accordion title="Check our Cookbook" icon="github">
    To explore code examples and get reusable snippets, explore our official cookbook with solutions, examples and demo apps:

    [https://github.com/nebius/token-factory-cookbook](https://github.com/nebius/token-factory-cookbook)
  </Accordion>
</AccordionGroup>

## Explore

**Nebius Token Factory** is your all-in-one platform for working with large language models (LLMs) — from quick experimentation to production deployment. Test and compare models in an intuitive **playground**, or integrate them into your applications via an **OpenAI-compatible API** for **inference and fine-tuning**, and extend capabilities through **seamless integrations with popular frameworks**.

<CardGroup>
  <Card title="Inference" icon="bolt" href="/ai-models-inference/overview">
    Send requests such as prompts, chats or images, and get responses
  </Card>

  <Card title="Third-party integrations" icon="chart-network" href="/integrations/overview">
    Build inference into applications that are based on supported third-party integrations
  </Card>

  <Card title="Fine-tuning" icon="layer-group" href="/fine-tuning/overview">
    Train models by using datasets to increase output accuracy, enhance model reliability and save costs on prompting
  </Card>

  <Card title="API" icon="code" href="/api-reference/introduction">
    Learn how to authenticate and make requests to the inference API
  </Card>
</CardGroup>


# agent - Coding-agent manual
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/agent



Display the coding-agent manual — a guide for AI agents and automated
workflows using contree-cli.

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree agent --help</div></div><pre><code><span>usage: </span><span>contree agent</span><span> \[</span><span>-h</span><span>]</span><br /><span>                     </span><span>\[\{all,all\_commands,command,command\_safety,core,core\_workflow,execution,execution\_modes,files,files\_and\_directories,images,images\_and\_tags,output,output\_formats,profiles,sessions}]</span><br /><br /><span>Show the manual.</span><br /><br /><span>\`contree agent \[TOPIC]\` prints the built-in manual.</span><br /><span>\`contree man\` is an alias.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{all,all\_commands,command,command\_safety,core,core\_workflow,execution,execution\_modes,files,files\_and\_directories,images,images\_and\_tags,output,output\_formats,profiles,sessions}</span><br /><span>                        Manual topic (default: all)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><br /><span>examples:</span><br /><span>  contree agent</span><br /><span>  contree agent sessions</span><br /><span>  contree man commands</span></code></pre></div>

## Behavior

Prints instructions optimized for coding agents (Claude, Codex, etc.)
covering session management with `-S`, rollback-safe workflows, file
staging, and structured output.

Use this as a reference when building agent tool integrations or
writing `SKILL.md` prompts.


# auth - Configure credentials and profiles
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/auth



Configure authentication tokens and manage profiles. Each profile stores
credentials for a different project or environment.

## Examples

```bash theme={null}
# Save a token (secure prompt, no echo)
contree auth

# Save to a named profile
contree auth --profile=personal

# Force overwrite existing profile
contree auth -y

# List all profiles and probe whether they work
contree auth ls

# Structured output for scripts and agents
contree -o json auth ls

# List profiles without network probes
contree auth ls --offline

# Switch active profile
contree auth switch personal

# Remove a profile
contree auth remove personal
contree auth rm personal -y
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree auth --help</div></div><pre><code><span>usage: </span><span>contree auth</span><span> \[</span><span>-h</span><span>] \[</span><span>--token </span><span>AUTH\_TOKEN</span><span>] \[</span><span>-u </span><span>AUTH\_URL</span><span>] \[</span><span>--type </span><span>\{iam,jwt}</span><span>] \[</span><span>-P </span><span>AUTH\_PROJECT</span><span>]</span><br /><span>                    \[</span><span>-p </span><span>PROFILE</span><span>] \[</span><span>-f</span><span>]</span><br /><span>                    </span><span>\{list,ls,profiles,switch,remove,rm,del} ...</span><br /><br /><span>Configure authentication credentials.</span><br /><br /><span>Validates a token against the API (GET /v1/whoami) and saves it to the</span><br /><span>config file under the specified profile. The token is prompted securely</span><br /><span>via getpass if --token is not provided.</span><br /><br /><span>Supports two auth types:</span><br /><span>  iam (default) — bearer token + project ID, default URL provided</span><br /><span>  jwt (legacy)  — bearer token only, URL must be specified</span><br /><br /><span>Environment variable fallbacks during registration:</span><br /><span>  CONTREE\_TOKEN / NEBIUS\_API\_KEY     used when --token is omitted</span><br /><span>  CONTREE\_URL                        used when --url is omitted</span><br /><span>  CONTREE\_PROJECT / NEBIUS\_AI\_PROJECT used when --project is omitted (IAM)</span><br /><br /><span>Other commands ignore these variables; only \`\`contree auth\`\` reads</span><br /><span>them. \`\`CONTREE\_PROFILE\`\` selects the profile for any command.</span><br /><br /><span>Subcommands:</span><br /><span>  profiles    List saved profiles (\* marks active)</span><br /><span>  switch NAME Switch the active profile</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{list,ls,profiles,switch,remove,rm,del}</span><br /><span>    </span><span>list (ls, profiles)</span><br /><span>                        List saved profiles</span><br /><span>    </span><span>switch</span><span>              Switch active profile</span><br /><span>    </span><span>remove (rm, del)</span><span>    Remove a saved profile</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>--token</span><span> </span><span>AUTH\_TOKEN</span><span>    API token (prompted if omitted)</span><br /><span>  </span><span>-u</span><span>, </span><span>--url</span><span> </span><span>AUTH\_URL</span><span>    API base URL</span><br /><span>  </span><span>--type</span><span> </span><span>\{iam,jwt}</span><span>      Auth type (default: iam)</span><br /><span>  </span><span>-P</span><span>, </span><span>--project</span><span> </span><span>AUTH\_PROJECT</span><br /><span>                        Project ID (IAM only)</span><br /><span>  </span><span>-p</span><span>, </span><span>--profile</span><span> </span><span>PROFILE</span><br /><span>                        Profile name (default: default)</span><br /><span>  </span><span>-f</span><span>, </span><span>-y</span><span>, </span><span>--force</span><span>       Overwrite existing profile without confirmation</span><br /><br /><span>for coding agents:</span><br /><span>  \`auth\` verifies token with /v1/whoami before writing config</span><br /><span>  mutates local config file and may prompt for token if omitted</span><br /><span>  use \`auth profiles\` for read-only profile discovery</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

When you run `contree auth`, the CLI:

1. Prompts for the **token** securely via `getpass` (no echo, not stored in
   shell history)
2. Prompts for the **project ID**
3. Verifies the token with the API (`GET /v1/whoami`)
4. Writes credentials to `~/.config/contree/auth.ini`
5. If the profile already exists, prompts for confirmation (use `-y`
   to skip)

### Flags

* `--token` — API token (prompted securely if omitted)
* `--url` — API base URL (default: `https://api.tokenfactory.nebius.com/sandboxes`)
* `--project` — Project ID (prompted if omitted)
* `--profile` — Profile name (default: `default`)
* `-y` / `--force` — Overwrite existing profile without confirmation

### Environment variable shortcuts

When CLI flags (`--token`, `--url`, `--project`) are not passed,
`contree auth` checks these environment variables before falling back
to an interactive prompt:

| Variable            | Fallback for | Priority                                                |
| ------------------- | ------------ | ------------------------------------------------------- |
| `CONTREE_TOKEN`     | `--token`    | flag > `CONTREE_TOKEN` > `NEBIUS_API_KEY` > prompt      |
| `NEBIUS_API_KEY`    | `--token`    | (see above)                                             |
| `CONTREE_URL`       | `--url`      | flag > env > type-specific default > prompt             |
| `CONTREE_PROJECT`   | `--project`  | flag > `CONTREE_PROJECT` > `NEBIUS_AI_PROJECT` > prompt |
| `NEBIUS_AI_PROJECT` | `--project`  | (see above)                                             |

These variables are read **only** during `contree auth`. Other commands
ignore them and read credentials strictly from the saved profile.

If the relevant variables are set, `contree auth` runs fully
non-interactively (no prompts):

```bash theme={null}
export NEBIUS_API_KEY=eyJ...
export NEBIUS_AI_PROJECT=your-project-id
contree auth -y      # no prompts, saves immediately
```

## `auth list`

`contree auth list` (alias `auth ls`, `profiles`) prints every saved
profile from `auth.ini` and verifies each one against the API with a
2-second timeout, adding a `status` column that tells you at a glance
which profiles are usable. Pass `--offline` to suppress the probe
entirely when you only want to inspect what is saved locally.

<div><div><div><span /><span /><span /></div><div>\$ contree auth list --help</div></div><pre><code><span>usage: </span><span>contree auth list</span><span> \[</span><span>-h</span><span>] \[</span><span>-O</span><span>]</span><br /><br /><span>List configured local profiles and active marker.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>     show this help message and exit</span><br /><span>  </span><span>-O</span><span>, </span><span>--offline</span><span>  Do not probe /v1/whoami; mark all profile statuses as offline</span><br /><br /><span>for coding agents: read-only command</span></code></pre></div>

Possible `status` values:

* `ok` – probe succeeded and the token has the `list` permission
* `inactive` – probe succeeded but the token lacks the `list`
  permission, meaning sandboxes are disabled on this project
* `timeout` – probe did not complete within 2 seconds
* `error` – probe failed for another reason, such as a bad token or
  another network/API error
* `offline` – you passed `--offline`, so no probe was attempted

For automation and agents, prefer:

```bash theme={null}
contree -o json auth ls
contree -o json auth ls --offline
```

## `auth switch`

`contree auth switch NAME` rewrites the `active` pointer in `auth.ini`
so subsequent commands resolve credentials from that profile. The
profile must already exist (created by `contree auth --profile=NAME`).
Switching does not touch token data, so it is safe to run as often as
you like to bounce between projects.

<div><div><div><span /><span /><span /></div><div>\$ contree auth switch --help</div></div><pre><code><span>usage: </span><span>contree auth switch</span><span> \[</span><span>-h</span><span>] </span><span>profile\_name</span><br /><br /><span>Set \[DEFAULT] profile in local config file.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>profile\_name</span><span>  Profile to activate</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>    show this help message and exit</span><br /><br /><span>for coding agents: mutates local config state</span></code></pre></div>

## `auth remove`

`contree auth remove NAME` (aliases `rm`, `del`) deletes the profile
from `auth.ini` and removes its per-profile session database
(`sessions-NAME.db`). If the deleted profile was the active one, the
CLI promotes the first remaining profile to active (or falls back to
`default` if none remain). Confirmation is required unless `-y` is
passed.

<div><div><div><span /><span /><span /></div><div>\$ contree auth remove --help</div></div><pre><code><span>usage: </span><span>contree auth remove</span><span> \[</span><span>-h</span><span>] \[</span><span>-f</span><span>] </span><span>profile\_name</span><br /><br /><span>Delete a profile section from config.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>profile\_name</span><span>     Profile to remove</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><span>  </span><span>-f</span><span>, </span><span>-y</span><span>, </span><span>--force</span><span>  Do not ask for confirmation</span><br /><br /><span>for coding agents: mutates local config state</span></code></pre></div>

```bash theme={null}
contree auth remove personal
contree auth rm personal         # alias
contree auth del personal -y     # skip confirmation
```

<Warning>
  Avoid `--token=eyJ...` on the command line — the token is visible in
  process listings (`ps`) and shell history. Omit `--token` to use the
  secure prompt instead.
</Warning>

## Alternative authentication

Runtime commands always read credentials from the saved profile.
To authenticate without an interactive `auth` flow, either:

```bash theme={null}
# 1. Bootstrap the profile non-interactively from environment vars
export CONTREE_TOKEN=eyJ...
export CONTREE_URL=https://api.tokenfactory.nebius.com/sandboxes
contree auth -y --type jwt
contree images

# 2. Or pass the token inline per-command (visible in process listings)
contree --token=eyJ... images
```

Setting `CONTREE_TOKEN` alone (without first running `contree auth`)
will not authenticate runtime commands.

## See also

* [Install & Authenticate](../tutorial/installation) – full authentication guide
* [Configuration & Profiles](../tutorial/configuration) – config file format and precedence


# build - Build an image from a Dockerfile
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/build



Build an image from a `Dockerfile`. Each directive runs against the
contree API and produces a new image layer; successful layers are
materialised as branches named `layer:<chain-hash>` so re-running the
same Dockerfile reuses prior work.

## Synopsis

```bash theme={null}
contree build [CONTEXT] [--dockerfile PATH] [--tag NAME[:TAG]]
              [--build-arg K=V ...] [--no-cache] [--timeout SEC]
```

* `CONTEXT` – build context directory (default `.`).
* `--dockerfile PATH` – override the default `<CONTEXT>/Dockerfile`.
* `--tag NAME[:TAG]` – tag the final image via `PATCH /v1/images/{uuid}/tag`.
* `--build-arg KEY=VALUE` – supply a value for an `ARG` declared in the
  Dockerfile (repeatable).
* `--no-cache` – ignore existing `layer:<hash>` branches and rebuild.
* `--timeout SEC` – per-`RUN` operation timeout in seconds (default 600).

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree build --help</div></div><pre><code><span>usage: </span><span>contree build</span><span> \[</span><span>-h</span><span>] \[</span><span>--dockerfile </span><span>PATH</span><span>] \[</span><span>--tag </span><span>NAME\[:TAG]</span><span>] \[</span><span>--build-arg </span><span>KEY=VALUE</span><span>]</span><br /><span>                     \[</span><span>--no-cache</span><span>] \[</span><span>-t </span><span>TIMEOUT</span><span>]</span><br /><span>                     </span><span>\[context]</span><br /><br /><span>Build an image from a Dockerfile.</span><br /><br /><span>Reads the Dockerfile at the given path (default \`\`\<CONTEXT>/Dockerfile\`\`)</span><br /><span>and applies each directive against an isolated build session keyed by</span><br /><span>the absolute path of the context directory. Successful layers are</span><br /><span>materialised as branches named \`\`layer:\<chain-hash>\`\` so that</span><br /><span>re-running the same Dockerfile reuses prior work.</span><br /><br /><span>Supported directives (MVP): FROM (multistage via \`\`FROM ... AS name\`\`),</span><br /><span>RUN, COPY (including \`\`--from=\<alias|index|image>\`\`), ADD (local</span><br /><span>files/dirs and http(s) URLs; no tar auto-extraction, no \`\`--from\`\`),</span><br /><span>WORKDIR, ENV, ARG, USER. Other Dockerfile directives parse cleanly but</span><br /><span>are skipped with a warning (CMD, ENTRYPOINT, LABEL, EXPOSE, VOLUME,</span><br /><span>STOPSIGNAL, MAINTAINER, HEALTHCHECK, ONBUILD, SHELL).</span><br /><br /><span>Multistage notes: \`\`COPY --from\`\` exports the source path from the</span><br /><span>referenced stage image as a tar archive, uploads it once (content</span><br /><span>deduplicated) and unpacks it with an extraction RUN inside the target</span><br /><span>sandbox. For now this means the target image must provide \`\`/bin/sh\`\`,</span><br /><span>\`\`tar\`\`, \`\`cp\`\` and \`\`mv\`\` (busybox suffices; \`\`FROM scratch\`\` targets</span><br /><span>cannot receive \`\`COPY --from\`\`). This is a temporary limitation of the</span><br /><span>client-side extraction and will be lifted in a future release once the</span><br /><span>backend unpacks archives itself. Unlike docker, ARG/ENV live in one</span><br /><span>global namespace across stages.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>context</span><span>               Build context directory (default: .)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>--dockerfile</span><span> </span><span>PATH</span><span>     Dockerfile path (default: \<context>/Dockerfile) (default: )</span><br /><span>  </span><span>--tag</span><span> </span><span>NAME\[:TAG]</span><span>      Tag the final image (default: )</span><br /><span>  </span><span>--build-arg</span><span> </span><span>KEY=VALUE</span><br /><span>                        Build-time variable (repeatable)</span><br /><span>  </span><span>--no-cache</span><span>            Ignore cached layers and rebuild</span><br /><span>  </span><span>-t</span><span>, </span><span>--timeout</span><span> </span><span>TIMEOUT</span><br /><span>                        Timeout in seconds for each RUN step (default: 600)</span><br /><br /><span>examples:</span><br /><span>  contree build .</span><br /><span>  contree build . --tag myimage:latest</span><br /><span>  contree build --dockerfile ./Dockerfile.test ./app</span><br /><span>  contree build --build-arg VERSION=1.2 .</span><br /><span>  contree build --no-cache .</span><br /><br /><span>for coding agents:</span><br /><span>  mutating command, may create operations against the API</span><br /><span>  layer cache is per-context (session keyed by abspath(context))</span><br /><span>  use --no-cache to bypass cached layers and rebuild from scratch</span><br /><span>  multistage supported: FROM ... AS name + COPY --from=\<name|index|image></span><br /><span>  COPY --from unpacks a tar inside the target: needs sh/tar/cp/mv there</span><br /><span>  (temporary limitation, to be lifted in a future release)</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Examples

```bash theme={null}
# Simplest build; finds ./Dockerfile, tags the result
contree build . --tag myapp:dev

# Out-of-tree Dockerfile
contree build ./service --dockerfile ./service/Dockerfile.prod --tag svc:prod

# Override build-time variables
contree build . --build-arg VERSION=2.5 --build-arg DEBUG=1

# Force a rebuild ignoring cached layers
contree build . --no-cache --tag myapp:dev
```

## Supported directives (MVP)

| Directive                                                                                                       | Behaviour                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FROM ref[:tag] [AS name]`                                                                                      | Resolves the base image. If the tag is not found locally, the build auto-imports it via `POST /v1/images/import`. `AS name` is parsed but ignored (multi-stage is Phase 2).                                                                                                                                                               |
| `RUN ...`                                                                                                       | Shell-form (`RUN echo hi`) or JSON exec-form (`RUN ["echo","hi"]`). Spawns `POST /v1/instances`, polls until terminal status, captures the resulting image.                                                                                                                                                                               |
| `COPY [--chown=...] [--chmod=...] SRC... DEST`                                                                  | Walks local sources relative to the build context, applies `.dockerignore`, uploads files (with SHA256 dedup), and stages them for the next `RUN`.                                                                                                                                                                                        |
| `ADD ...`                                                                                                       | Local paths behave like `COPY`. `https://`/`http://` URLs are **streamed straight from the source socket into `POST /v1/files`** (no temp file on disk); the URL plus its `ETag`/`Last-Modified`/`Content-MD5` validators are cached so repeat builds skip the download via a conditional `HEAD`. Tar auto-extraction is not implemented. |
| `WORKDIR /path`                                                                                                 | Sets the working directory for subsequent directives.                                                                                                                                                                                                                                                                                     |
| `ENV KEY=VALUE ...`                                                                                             | Accumulates environment variables passed to every `RUN`.                                                                                                                                                                                                                                                                                  |
| `ARG NAME[=DEFAULT]`                                                                                            | Declares a build-time variable. Overridden by `--build-arg`.                                                                                                                                                                                                                                                                              |
| `USER name`                                                                                                     | Subsequent `RUN` commands are wrapped in `su -s /bin/sh -c '<cmd>' <name>`.                                                                                                                                                                                                                                                               |
| `CMD`, `ENTRYPOINT`, `LABEL`, `EXPOSE`, `VOLUME`, `STOPSIGNAL`, `MAINTAINER`, `HEALTHCHECK`, `ONBUILD`, `SHELL` | Parsed but skipped with a warning.                                                                                                                                                                                                                                                                                                        |

`COPY --from=stage` is a Phase 2 feature; in MVP it warns and skips.

## Sessions and layer cache

Builds run in a dedicated session keyed by the absolute path of the
context directory: `build:<sha16(abspath(context))>`. Re-running the
same Dockerfile in the same context reuses cached layers across
invocations of `contree build`; switching to `--no-cache` rebuilds
everything.

Layers are stored as branches whose names are the chain-hash of:

```
sha256(parent_layer_hash || state(workdir/env/user/args) || directive || pending_files)
```

To inspect the resulting branches:

```bash theme={null}
contree session list --filter build:
contree session show
```

<Note>
  `build` is **project-scoped from the user’s point of view**: it does
  not bind to the agent’s `-S <key>` session. Passing `-S` is harmless
  but does not move that key’s image. After a successful build, attach
  the result to your normal agent session by tag:

  ```bash theme={null}
  contree build . --tag myapp:dev
  contree -S agent_verify use tag:myapp:dev
  contree -S agent_verify run -D -- myapp --version
  ```
</Note>

## `.dockerignore`

`contree build` reads `<CONTEXT>/.dockerignore` and filters every
`COPY`/`ADD` walk. Rules are matched in order against POSIX-style
paths relative to the context root; the last matching rule wins,
so `!` re-includes a previously ignored path.

```
# .dockerignore
**/*.log
.env*
node_modules
!logs/keep.log
```

Globs:

* `*` matches a single path segment (does not cross `/`).
* `**` matches zero or more path components.
* `?` matches one character.
* `[abc]` is a character class.
* Trailing `/` matches a directory and everything below it.

The default exclude list from `run --file` (`.git`, `*.pyc`,
`__pycache__`, `.venv`, `node_modules`, `dist`, `build`, etc.) is
always applied on top of `.dockerignore`.

## Variable substitution

`$VAR` and `${VAR}` are expanded in `FROM`, `RUN`, `COPY`/`ADD`
arguments, `WORKDIR`, `ENV` values, and `USER`. The value source is:

1. `--build-arg KEY=VALUE` (highest priority for declared `ARG` names).
2. `ENV` directives processed so far.
3. `ARG` defaults.
4. Empty string for unknown names.

## End-to-end demo

A small example lives in `docs/examples/build-demo/`. The Dockerfile
exercises `FROM`, `ARG`, `ENV`, `WORKDIR`, two `COPY` directives (file
and directory), and two `RUN` directives. A `.dockerignore` filters
log files and `__pycache__` from the upload.

```dockerfile theme={null}
% docs/examples/build-demo/Dockerfile
FROM python:3.12-alpine

ARG GREETING=hello
ENV APP_GREETING=${GREETING}

WORKDIR /app

COPY hello.py /app/hello.py
COPY src /app/src
ADD https://github.com/nebius/contree-cli/archive/refs/heads/master.zip /tmp/contree-cli.zip

RUN python -c "import sys; print('python', sys.version)"
RUN python -m zipfile -e /tmp/contree-cli.zip /opt/
RUN pip install --no-cache-dir /opt/contree-cli-master
RUN contree --help | head -20
RUN python /app/hello.py
```

The `ADD` line streams the zip straight from GitHub into the contree
API (no local temp file). The subsequent `RUN` steps unpack it,
`pip install` the project, and prove the installed `contree` binary
works inside the built image.

```dockerfile theme={null}
% docs/examples/build-demo/.dockerignore
**/*.log
**/__pycache__
.env*
```

Build and tag it:

```bash theme={null}
contree build docs/examples/build-demo --tag contree-cli-build-demo:latest
```

Expected output (truncated):

```text theme={null}
[INFO] RUN spawned op=019e... RUN python -c "import sys; print('python', sys.version)"
[INFO] stdout:
python 3.12.13 ...

[INFO] RUN spawned op=019e... RUN python /app/hello.py
[INFO] stdout:
+---------------+
|     hello     |
| contree build |
+---------------+

[INFO] tagged <uuid> as contree-cli-build-demo:latest
IMAGE                                 TAG                            SESSION
<uuid>                                contree-cli-build-demo:latest  build:<sha16>
```

Re-running the same command without `--no-cache` produces layer cache
hits, and the `ADD URL` step short-circuits at the `HEAD` probe (look
for `URL cache hit (HEAD validators match)` in the log) – no body
download, no upload.

## See also

* [run - Execute a command in the sandbox](./run) – the single-shot version of what `RUN` does.
* [session - Manage sessions, branches, history](./session) – inspect or branch the layer history.
* [images - List and import images](./images) – list, import, and tag images directly.


# cat - Show file content from the image
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/cat



Display the contents of a file from the session image.

## Examples

```bash theme={null}
# View a text file
contree cat /etc/os-release

# Pipe to another command
contree cat /var/log/app.log | grep ERROR

# Redirect to a local file
contree cat /etc/nginx/nginx.conf > nginx.conf
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree cat --help</div></div><pre><code><span>usage: </span><span>contree cat</span><span> \[</span><span>-h</span><span>] </span><span>path</span><br /><br /><span>Show file content from the session image.</span><br /><br /><span>Downloads and displays a file from the current session image via the</span><br /><span>/inspect/ API without spawning an instance. Binary files are refused</span><br /><span>when stdout is a terminal — use shell redirection or \`contree cp\` to</span><br /><span>save them locally.</span><br /><br /><span>Results are cached per (image, path) so repeated reads are instant.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>path</span><span>        Path inside image</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  read-only command (inspect API, no instance spawn)</span><br /><span>  binary output is blocked on interactive TTY; pipe or use cp for binaries</span><br /><span>  --format is ignored; output is raw file content</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

The file is read directly from the image – no sandbox is started.

Binary files are detected and refused when output is a terminal (to protect
your shell). Redirect to a file or pipe to another command to handle binary
content:

```bash theme={null}
contree cat /usr/bin/curl > curl
```

For downloading files to a specific local path, use [cp - Download a file from the image](./cp) instead.

## See also

* [ls - List files in the image](./ls) – list files before viewing
* [cp - Download a file from the image](./cp) – download to a local path with progress


# cd - Change session working directory
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/cd



Change the working directory for subsequent commands in the current session.

## Examples

```bash theme={null}
contree cd /app
contree run -- ls           # runs in /app
contree cd /etc
contree cat os-release      # reads /etc/os-release
contree cd                  # print current working directory
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree cd --help</div></div><pre><code><span>usage: </span><span>contree cd</span><span> \[</span><span>-h</span><span>] </span><span>\[path]</span><br /><br /><span>Change the working directory in the current session.</span><br /><br /><span>Sets the session's cwd used by subsequent commands (run, ls, cat).</span><br /><span>Relative paths are resolved against the current cwd. Without an</span><br /><span>argument, prints the current working directory.</span><br /><br /><span>The path is validated against the image filesystem via the inspect API.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>path</span><span>        Target directory</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  mutates local session cwd pointer</span><br /><span>  validates path exists in image via inspect API</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

`cd` stores the path in the session state. Subsequent `run`, `ls`, `cat`,
and `cp` commands resolve relative paths against it.

`cd` without arguments prints the current working directory.

<Note>
  `cd` validates the target against the image filesystem via the
  inspect API and reports an error when the directory does not exist.
</Note>


# cp - Download a file from the image
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/cp



Download a file from the session image to a local path.

## Examples

```bash theme={null}
# Copy a config file locally
contree cp /etc/nginx/nginx.conf ./nginx.conf

# Download a build artifact
contree cp /app/dist/output.tar.gz ./output.tar.gz
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree cp --help</div></div><pre><code><span>usage: </span><span>contree cp</span><span> \[</span><span>-h</span><span>] </span><span>path</span><span> </span><span>dest</span><br /><br /><span>Copy a file from the session image to a local path.</span><br /><br /><span>Downloads the file at PATH inside the current session image and writes</span><br /><span>it to DEST on the local filesystem. Progress is logged for large files.</span><br /><span>Unlike \`cat\`, this command handles binary content and does not require</span><br /><span>a terminal.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>path</span><span>        Path inside image</span><br /><span>  </span><span>dest</span><span>        Local destination path</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  read-only command against remote image, writes local file DEST</span><br /><span>  suitable for binary files</span><br /><span>  --format is ignored; command writes bytes directly</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

The file is streamed from the image directly – no sandbox is started.

For large files, progress is logged every 5 seconds with download speed
and ETA. The final log line shows total size and average speed.

## See also

* [ls - List files in the image](./ls) – list files to find the path
* [cat - Show file content from the image](./cat) – view file contents without downloading
* [Your First Sandbox](../tutorial/first-steps) – downloading files


# env - Manage session environment variables
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/env



Manage session-level environment variables. Variables set with `env` are
applied to every `contree run` automatically. Per-run `-e` flags override
session env vars with the same key.

## Examples

```bash theme={null}
# Set PATH after installing tools
contree env PATH=/root/.cargo/bin:/usr/local/bin:/usr/bin:/bin:/sbin

# Set multiple variables
contree env DEBUG=1 DB_HOST=localhost

# List current session env
contree env

# Unset variables
contree env -U PATH
contree env -U DEBUG DB_HOST

# Per-run -e overrides session env
contree run -e DEBUG=0 -- ./app
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree env --help</div></div><pre><code><span>usage: </span><span>contree env</span><span> \[</span><span>-h</span><span>] \[</span><span>-U</span><span>] </span><span>\[KEY=VALUE ...]</span><br /><br /><span>Manage session environment variables.</span><br /><br /><span>Session env vars are applied to every \`contree run\` automatically.</span><br /><span>Per-run \`-e\` flags override session env vars with the same key.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>KEY=VALUE</span><span>           Environment variables to set (or keys to delete with -d)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>          show this help message and exit</span><br /><span>  </span><span>-U</span><span>, </span><span>--delete</span><span>, </span><span>--rm</span><span>  Unset the specified environment variables</span><br /><br /><span>examples:</span><br /><span>  contree env                                  list session env vars</span><br /><span>  contree env PATH=/root/.cargo/bin:\$PATH      set PATH</span><br /><span>  contree env DEBUG=1 DB\_HOST=localhost         set multiple</span><br /><span>  contree env -U PATH                          unset PATH</span><br /><span>  contree env -U PATH DEBUG                    unset multiple</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

Session env vars are stored in SQLite per session. They persist across
terminal restarts (when using `-S` or `CONTREE_SESSION`).

When `contree run` builds the payload, it merges:

1. Session env vars (base)
2. Per-run `-e` flags (override)

Deleting a session (`session delete`) removes its env vars.

Values with `=` in them work correctly — only the first `=` is the
separator: `contree env CMD=a=b=c` sets `CMD` to `a=b=c`.


# file - Stage file edits for the next run
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/file



Stage file changes for the next `contree run`. Pending files are
automatically included without needing `--file` flags.

## Examples

```bash theme={null}
# Edit a file from the image in $EDITOR
contree file edit /etc/nginx/nginx.conf

# Stage a local file at a specific path
contree file cp ./config.yaml /etc/app/config.yaml

# Both edits apply on the next run
contree run nginx -t
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree file --help</div></div><pre><code><span>usage: </span><span>contree file</span><span> \[</span><span>-h</span><span>] </span><span>\{edit,e,cp,ls,list} ...</span><br /><br /><span>Manage files in the session image.</span><br /><br /><span>Subcommands:</span><br /><span>  edit (e)  Download a file from the session image, open it in \$EDITOR</span><br /><span>            (or vi), and upload the modified version as a pending file</span><br /><span>            attachment. The change takes effect on the next \`run\`.</span><br /><br /><span>  cp        Copy a local file into the session image as a pending file</span><br /><span>            attachment. The file is uploaded immediately but injected</span><br /><span>            into the sandbox on the next \`run\`.</span><br /><br /><span>Pending files are branch-aware — switching branches changes which</span><br /><span>files are visible.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{edit,e,cp,ls,list}</span><br /><span>    </span><span>edit (e)</span><span>           Edit a file in the session image</span><br /><span>    </span><span>cp</span><span>                 Copy a local file into the session image</span><br /><span>    </span><span>ls (list)</span><span>          List uploaded files (joined with local cache)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>           show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  mutating command (stages pending file changes for next run)</span><br /><span>  file edit PATH uses local editor and uploads on change</span><br /><span>  file cp SRC DEST uploads local file and stages DEST path</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Subcommands

### `file edit`

`contree file edit PATH` (alias `e`) downloads the file at `PATH` from
the session image, opens it in `$EDITOR` (defaults to `vi`), and stages
the modified buffer as a pending upload that will be injected into the
next `contree run`. Missing files are created as empty buffers so the
command doubles as `touch + open`.

<div><div><div><span /><span /><span /></div><div>\$ contree file edit --help</div></div><pre><code><span>usage: </span><span>contree file edit</span><span> \[</span><span>-h</span><span>] \[</span><span>-E </span><span>EDITOR</span><span>] </span><span>path</span><br /><br /><span>Edit a remote file via a local editor. The updated content is uploaded and staged as a pending</span><br /><span>file for the next run.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>path</span><span>                 Path inside image</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>           show this help message and exit</span><br /><span>  </span><span>-E</span><span>, </span><span>--editor</span><span> </span><span>EDITOR</span><span>  Editor command (default: /usr/bin/vim)</span><br /><br /><span>for coding agents: mutates session state (adds pending file entry) does not apply immediately;</span><br /><span>effect appears on next \`contree run\`</span></code></pre></div>

### `file cp`

`contree file cp SRC DEST` (alias `f`) reads a local file at `SRC`, uploads
it to the project’s file store, and stages it for delivery at `DEST` inside
the session image on the next `contree run`. Use this when you have a file
ready on disk locally and just want it materialised inside the sandbox
without spawning an instance first.

<div><div><div><span /><span /><span /></div><div>\$ contree file cp --help</div></div><pre><code><span>usage: </span><span>contree file cp</span><span> \[</span><span>-h</span><span>] </span><span>src</span><span> </span><span>dest</span><br /><br /><span>Upload a local file and stage it as a pending attachment to be injected on the next run.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>src</span><span>         Local file path</span><br /><span>  </span><span>dest</span><span>        Destination path inside image</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents: mutates session state (adds pending file entry) destination path is inside</span><br /><span>sandbox filesystem</span></code></pre></div>

### `file ls`

`contree file ls` lists files uploaded to the project (`GET /v1/files`)
and joins each row with the local upload cache. The `SOURCE` column shows
whatever this machine produced the file from:

* absolute host path for files uploaded via `run --file` or `COPY`;
* `https://...` URL for files fetched via `ADD URL`.

<Info>
  `SOURCE` resolves **only for files uploaded from this very machine**.
  The mapping lives in the local SQLite cache (per-profile, under
  `$CONTREE_HOME/cli/sessions/<profile>.db`) keyed by
  `path + inode + mtime + size` (host paths) or by the URL itself (URL
  fetches). It is **not** synced anywhere, so a row will show an empty
  `SOURCE` whenever:

  * the file was uploaded by a different machine, container, or teammate;
  * the file was uploaded by an earlier CLI version that did not yet
    track its origin (those entries backfill the next time the file is
    matched by the local cache);
  * the host file has been moved, renamed, or its `inode/mtime/size` has
    changed since upload (the cache key no longer matches and the
    mapping is treated as missing until the next upload).

  There is no way to recover the source of a file uploaded from another
  machine – the server stores only `uuid`, `sha256`, `size`,
  `created_at`, and `updated_at`.
</Info>

```bash theme={null}
contree file ls
contree file ls --since 1d --limit 200
contree file ls -q                # uuid + sha256 + source only
contree -o json file ls | jq 'select(.source != "")'
```

<div><div><div><span /><span /><span /></div><div>\$ contree file ls --help</div></div><pre><code><span>usage: </span><span>contree file ls</span><span> \[</span><span>-h</span><span>] \[</span><span>--since </span><span>SINCE</span><span>] \[</span><span>--until </span><span>UNTIL</span><span>] \[</span><span>--limit </span><span>LIMIT</span><span>] \[</span><span>-q</span><span>]</span><br /><br /><span>List remote files uploaded to the project and, when present in the local upload cache, show what</span><br /><span>produced them under the 'source' column: either an absolute host path (for run --file / COPY</span><br /><span>uploads) or a URL (for ADD URL). source is THIS-MACHINE ONLY: the mapping lives in the local CLI</span><br /><span>cache (\$CONTREE\_HOME/cli/sessions/\<profile>.db) and is never synced. Files uploaded from a</span><br /><span>different host, by a teammate, or before tracking landed will show an empty source -- that is</span><br /><span>expected, not a bug. Use the remote uuid or sha256 for cross-machine identity.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>     show this help message and exit</span><br /><span>  </span><span>--since</span><span> </span><span>SINCE</span><span>  Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.</span><br /><span>  </span><span>--until</span><span> </span><span>UNTIL</span><span>  Show files before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date to</span><br /><span>                 UTC datetime.</span><br /><span>  </span><span>--limit</span><span> </span><span>LIMIT</span><span>  Stop after this many files and warn if more are available</span><br /><span>  </span><span>-q</span><span>, </span><span>--quiet</span><span>    Emit only uuid, sha256, and source columns. source is populated only for files</span><br /><span>                 uploaded from this very machine.</span><br /><br /><span>examples: contree file ls contree file ls --since 1d contree file ls --limit 5000 contree file ls</span><br /><span>-q # uuid + sha256 + source contree -o json file ls</span></code></pre></div>

## Pending files

Pending files accumulate until the next `contree run` consumes them.
Explicit `--file` flags on `contree run` take priority over pending files
at the same path.

Files are uploaded with SHA256 dedup – identical content is not re-uploaded.

## See also

* [Working with Files](../tutorial/files) – full tutorial on file injection and editing
* [run - Execute a command in the sandbox](./run) – the `--file` syntax for inline file injection


# images - List and import images
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/images



List images in the project. Images are the filesystem snapshots that sandboxes
run from – every non-disposable `contree run` produces a new one.

## Examples

```bash theme={null}
# List all images
contree images

# Filter by tag prefix
contree images --prefix=ubuntu

# Include untagged intermediate images too
contree images -a

# Images created in the last hour
contree images --since=1h

# Find a specific image by UUID
contree images --uuid=3f2a7b1c-9d2e-4f60-8a1b-5c3d7e9f0a2b

# JSON output for scripting
contree -o json images | jq -r '.tag'
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree images --help</div></div><pre><code><span>usage: </span><span>contree images</span><span> \[</span><span>-h</span><span>] \[</span><span>--prefix </span><span>PREFIX</span><span>] \[</span><span>-i </span><span>UUID</span><span>] \[</span><span>-a</span><span>] \[</span><span>--since </span><span>SINCE</span><span>] \[</span><span>--until </span><span>UNTIL</span><span>]</span><br /><span>                      \[</span><span>--limit </span><span>LIMIT</span><span>]</span><br /><span>                      </span><span>\{list,ls,import} ...</span><br /><br /><span>List and import sandbox images.</span><br /><br /><span>Without a subcommand, lists images (same as \`\`images list\`\`).</span><br /><br /><span>Subcommands:</span><br /><span>  list (ls)     List images with filtering and pagination</span><br /><span>  import        Import image from a container registry</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{list,ls,import}</span><br /><span>    </span><span>list (ls)</span><span>       List images</span><br /><span>    </span><span>import</span><span>          Import image from container registry</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>        show this help message and exit</span><br /><span>  </span><span>--prefix</span><span> </span><span>PREFIX</span><span>   Filter by tag prefix</span><br /><span>  </span><span>-i</span><span>, </span><span>--uuid</span><span> </span><span>UUID</span><span>   Filter by image UUID</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>         Include untagged images (default: tagged only)</span><br /><span>  </span><span>--since</span><span> </span><span>SINCE</span><span>     Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.</span><br /><span>  </span><span>--until</span><span> </span><span>UNTIL</span><span>     Show images before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date</span><br /><span>                    to UTC datetime.</span><br /><span>  </span><span>--limit</span><span> </span><span>LIMIT</span><span>     Stop after this many images and warn if more are available (default: 3000)</span><br /><br /><span>examples:</span><br /><span>  contree images --prefix=ubuntu</span><br /><span>  contree images list --all</span><br /><span>  contree images import ubuntu:latest</span><br /><span>  contree images import ubuntu:\{latest,noble,jammy}</span><br /><span>  contree images import ghcr.io/owner/image:tag</span><br /><br /><span>for coding agents:</span><br /><span>  \`images\` / \`images list\` is read-only</span><br /><span>  \`images import\` spawns async import operations and polls until completion</span><br /><span>  supports brace expansion for batch imports</span><br /><span>  Ctrl+C cancels all active import operations</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Filtering

`--prefix` matches the beginning of the tag string. This is useful for
browsing available base images:

```bash theme={null}
contree images --prefix=python
contree images --prefix=common/
```

`--since` and `--until` accept either ISO timestamps or duration intervals
like `1h`, `30m`, `7d`.

## Subcommands

### `images list`

`contree images list` (alias `ls`) is the explicit form of the bare
`contree images` invocation. Both share the same flag set – pick the
explicit form when you want a command that reads symmetrically with
`images import`, or in scripts that already use the subcommand style
everywhere.

<div><div><div><span /><span /><span /></div><div>\$ contree images list --help</div></div><pre><code><span>usage: </span><span>contree images list</span><span> \[</span><span>-h</span><span>] \[</span><span>--prefix </span><span>PREFIX</span><span>] \[</span><span>-i </span><span>UUID</span><span>] \[</span><span>-a</span><span>] \[</span><span>--since </span><span>SINCE</span><span>] \[</span><span>--until </span><span>UNTIL</span><span>]</span><br /><span>                           \[</span><span>--limit </span><span>LIMIT</span><span>]</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><span>  </span><span>--prefix</span><span> </span><span>PREFIX</span><span>  Filter by tag prefix</span><br /><span>  </span><span>-i</span><span>, </span><span>--uuid</span><span> </span><span>UUID</span><span>  Filter by image UUID</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>        Include untagged images (default: tagged only)</span><br /><span>  </span><span>--since</span><span> </span><span>SINCE</span><span>    Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.</span><br /><span>  </span><span>--until</span><span> </span><span>UNTIL</span><span>    Show images before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date to</span><br /><span>                   UTC datetime.</span><br /><span>  </span><span>--limit</span><span> </span><span>LIMIT</span><span>    Stop after this many images and warn if more are available (default: 3000)</span></code></pre></div>

### `images import`

`contree images import REF [REF ...]` pulls one or more images from an
external OCI registry into the project and waits for the import
operation to finish. Each reference may be a `docker://` URL or any
form the platform accepts; multiple refs are imported sequentially with
shared credentials, and Ctrl-C cancels the in-flight operation cleanly.

<div><div><div><span /><span /><span /></div><div>\$ contree images import --help</div></div><pre><code><span>usage: </span><span>contree images import</span><span> \[</span><span>-h</span><span>] \[</span><span>--username </span><span>USERNAME</span><span>] \[</span><span>--password </span><span>PASSWORD</span><span>] \[</span><span>-t </span><span>TIMEOUT</span><span>]</span><br /><span>                             </span><span>refs \[refs ...]</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>refs</span><span>                  Image references (supports brace expansion)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>--username</span><span> </span><span>USERNAME</span><span>   Registry username (enables credentials)</span><br /><span>  </span><span>--password</span><span> </span><span>PASSWORD</span><span>   Registry password (prompted securely if --username given)</span><br /><span>  </span><span>-t</span><span>, </span><span>--timeout</span><span> </span><span>TIMEOUT</span><br /><span>                        Import timeout in seconds</span><br /><br /><span>examples:</span><br /><span>  contree images import ubuntu:latest</span><br /><span>  contree images import --timeout 600 ubuntu:latest</span><br /><span>  contree images import docker.io/ubuntu:latest</span><br /><span>  contree images import docker://docker.io/ubuntu:latest</span><br /><span>  contree images import ghcr.io/ubuntu/ubuntu:latest</span><br /><span>  contree images import ubuntu:\{latest,noble,jammy}</span><br /><br /><span>for coding agents:</span><br /><span>  mutating command — creates import operations</span><br /><span>  all formats are normalised to docker://registry/path:tag</span><br /><span>  polls every 5 seconds until all operations complete</span><br /><span>  Ctrl+C cancels all active import operations</span></code></pre></div>

## See also

* [tag - Tag or untag an image](./tag) – assign a tag to an image
* [Your First Sandbox](../tutorial/first-steps) – browsing and choosing images


# Command Reference
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/index



<div><div><div><span /><span /><span /></div><div>\$ contree --help</div></div><pre><code><span>usage: </span><span>contree</span><span> \[</span><span>-h</span><span>] \[</span><span>-v</span><span>] \[</span><span>-p </span><span>PROFILE</span><span>] \[</span><span>--token </span><span>TOKEN</span><span>] \[</span><span>-u </span><span>URL</span><span>] \[</span><span>-P </span><span>PROJECT</span><span>] \[</span><span>-c </span><span>CONFIG\_PATH</span><span>]</span><br /><span>               \[</span><span>-L </span><span>\{debug,info,warning,error,critical}</span><span>]</span><br /><span>               \[</span><span>-o </span><span>\{csv,default,json,json-pretty,plain,table,toml,tsv}</span><span>] \[</span><span>-S </span><span>SESSION\_KEY</span><span>]</span><br /><span>               </span><span>\{use,ci,run,r,build,bd,images,i,img,tag,t,ps,kill,show,operation,op,ls,cat,cp,export,file,f,session,s,auth,skill,cd,env,agent,man,shell,sh} ...</span><br /><br /><span>ConTree CLI - command-line client for the ConTree sandbox platform.</span><br /><br /><span>Run sandboxes, manage images, inspect filesystems, and track operations</span><br /><span>through the ConTree REST API.</span><br /><br /><span>Authentication:</span><br /><span>  Bearer token + project ID. Default API URL:</span><br /><span>    [https://api.tokenfactory.nebius.com/sandboxes/](https://api.tokenfactory.nebius.com/sandboxes/)</span><br /><br /><span>  Use \`contree auth --help\` to configure persistent credentials.</span><br /><br /><span>Coding-agent bootstrap (important):</span><br /><span>  Agents should read \`contree agent\` before executing task commands.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{use,ci,run,r,build,bd,images,i,img,tag,t,ps,kill,show,operation,op,ls,cat,cp,export,file,f,session,s,auth,skill,cd,env,agent,man,shell,sh}</span><br /><span>    </span><span>use (ci)</span><span>            Set or show current session image</span><br /><span>    </span><span>run (r)</span><span>             Spawn a sandbox instance</span><br /><span>    </span><span>build (bd)</span><span>          Build image from Dockerfile</span><br /><span>    </span><span>images (i, img)</span><span>     List and import images</span><br /><span>    </span><span>tag (t)</span><span>             Tag an image</span><br /><span>    </span><span>ps</span><span>                  List operations (alias for \`operation ls\`)</span><br /><span>    </span><span>kill</span><span>                Cancel operations (alias for \`operation cancel\`)</span><br /><span>    </span><span>show</span><span>                Show operation result (alias for \`operation show\`)</span><br /><span>    </span><span>operation (op)</span><span>      Manage operations (list/show/cancel)</span><br /><span>    </span><span>ls</span><span>                  List files in image</span><br /><span>    </span><span>cat</span><span>                 Show file content from image</span><br /><span>    </span><span>cp</span><span>                  Copy file from image to local path</span><br /><span>    </span><span>export</span><span>              Export image rootfs or a subtree as tar.gz</span><br /><span>    </span><span>file (f)</span><span>            Manage files in session image</span><br /><span>    </span><span>session (s)</span><span>         Manage session branches and history</span><br /><span>    </span><span>auth</span><span>                Configure authentication</span><br /><span>    </span><span>skill</span><span>               Manage agent skills</span><br /><span>    </span><span>cd</span><span>                  Change working directory</span><br /><span>    </span><span>env</span><span>                 Manage session environment variables</span><br /><span>    </span><span>agent (man)</span><span>         Show manual</span><br /><span>    </span><span>shell (sh)</span><span>          Interactive shell mode</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>-v</span><span>, </span><span>--version</span><span>         show program's version number and exit</span><br /><span>  </span><span>-p</span><span>, </span><span>--profile</span><span> </span><span>PROFILE</span><br /><span>                        Use this profile for the current command</span><br /><span>  </span><span>--token</span><span> </span><span>TOKEN</span><span>         API token (overrides profile for this invocation)</span><br /><span>  </span><span>-u</span><span>, </span><span>--url</span><span> </span><span>URL</span><span>         API base URL (overrides profile for this invocation)</span><br /><span>  </span><span>-P</span><span>, </span><span>--project</span><span> </span><span>PROJECT</span><br /><span>                        Project ID (overrides profile for this invocation)</span><br /><span>  </span><span>-c</span><span>, </span><span>--config</span><span> </span><span>CONFIG\_PATH</span><br /><span>                        Config file path (default: /home/runner/.config/contree/auth.ini)</span><br /><span>  </span><span>-L</span><span>, </span><span>--log-level</span><span> </span><span>\{debug,info,warning,error,critical}</span><br /><span>                        Logging level (default: info)</span><br /><span>  </span><span>-o</span><span>, </span><span>--format</span><span>, </span><span>--output</span><span> </span><span>\{csv,default,json,json-pretty,plain,table,toml,tsv}</span><br /><span>                        Output format (default: default)</span><br /><span>  </span><span>-S</span><span>, </span><span>--session</span><span> </span><span>SESSION\_KEY</span><br /><span>                        Session key override (alternative to CONTREE\_SESSION)</span><br /><br /><span>examples:</span><br /><span>  contree use tag:ubuntu:latest       set session image</span><br /><span>  eval \$(contree use tag:ubuntu:latest)  set + export env var</span><br /><span>  contree run -- uname -a            run command in session image</span><br /><span>  contree run --shell -- 'echo hi'   shell mode</span><br /><span>  contree run --file ./app.py:/app.py --disposable -- python /app.py</span><br /><span>  contree run --file ./src:/app/src -- make -C /app/src</span><br /><span>  contree images --prefix=ubuntu</span><br /><span>  contree ps -q</span><br /><span>  contree op ls                       same as \`contree ps\`</span><br /><span>  contree op show UUID1 UUID2         multi-UUID show</span><br /><span>  contree op cancel UUID1 UUID2       multi-UUID cancel (or --all)</span><br /><span>  contree show OPERATION\_UUID</span><br /><span>  contree tag IMAGE\_UUID latest</span><br /><span>  contree ls /etc                    list files in session image</span><br /><span>  contree cat /etc/os-release        show file from session image</span><br /><span>  contree auth                       save token (secure prompt)</span><br /><span>  contree auth switch staging</span><br /><span>  contree man                        user manual</span><br /><span>  contree agent                      coding-agent manual</span><br /><br /><span>for users:</span><br /><span>  contree man</span><br /><br /><span>for coding agents (required bootstrap):</span><br /><span>  1) read: contree agent</span><br /><span>  2) inspect command syntax: contree \<command> --help</span><br /><span>  3) only then execute task commands</span><br /><br /><span>before running tasks:</span><br /><span>  ensure auth exists; if missing/invalid, ask user to run \`contree auth\`</span><br /><br /><span>high-signal read-only commands:</span><br /><span>  contree images | ps | show UUID | ls \[PATH] | cat PATH | session | session show</span><br /><br /><span>mutating commands (change remote or local session state):</span><br /><span>  contree use IMAGE | run -- CMD | file edit PATH | file cp SRC DEST</span><br /><span>  contree tag UUID TAG | kill UUID | cd PATH | session checkout BRANCH</span><br /><br /><span>environment variables:</span><br /><span>  CONTREE\_PROFILE          Active config profile (selects which profile to use)</span><br /><span>  CONTREE\_SESSION          Explicit session name (for multi-terminal workflows).</span><br /><span>                           If unset, contree auto-generates \<cwd>+\<8hex> (derived</span><br /><span>                           from profile+ppid+tty); export your own for stable</span><br /><span>                           reuse. You can also pass -S/--session instead.</span><br /><span>  CONTREE\_SESSION\_DB       Path to session SQLite database</span><br /><span>  CONTREE\_NO\_UPDATE\_CHECK  Set to any value to disable PyPI update checks</span><br /><br /><span>registration-time fallbacks (only read by \`contree auth\`, not at runtime):</span><br /><span>  CONTREE\_TOKEN / NEBIUS\_API\_KEY        Token used when --token is omitted</span><br /><span>  CONTREE\_URL                           URL used when --url is omitted</span><br /><span>  CONTREE\_PROJECT / NEBIUS\_AI\_PROJECT   Project ID used when --project is omitted</span></code></pre></div>

<Columns>
  <Card title="auth - Configure credentials and profiles" href="./auth" icon="key" />

  <Card title="use - Choose an image for the session" href="./use" icon="cube" />

  <Card title="run - Execute a command in the sandbox" href="./run" icon="play" />

  <Card title="build - Build an image from a Dockerfile" href="./build" icon="hammer" />

  <Card title="images - List and import images" href="./images" icon="layer-group" />

  <Card title="tag - Tag or untag an image" href="./tag" icon="tag" />

  <Card title="operation - Manage operations" href="./operation" icon="spinner" />

  <Card title="ps - List activity" href="./ps" icon="list" />

  <Card title="show - Inspect an operation" href="./show" icon="magnifying-glass" />

  <Card title="kill - Cancel operations" href="./kill" icon="circle-xmark" />

  <Card title="ls - List files in the image" href="./ls" icon="list-ul" />

  <Card title="cat - Show file content from the image" href="./cat" icon="file-lines" />

  <Card title="cp - Download a file from the image" href="./cp" icon="copy" />

  <Card title="cd - Change session working directory" href="./cd" icon="folder" />

  <Card title="env - Manage session environment variables" href="./env" icon="leaf" />

  <Card title="file - Stage file edits for the next run" href="./file" icon="file" />

  <Card title="session - Manage sessions, branches, history" href="./session" icon="clock" />

  <Card title="shell - Interactive REPL" href="./shell" icon="terminal" />

  <Card title="skill - Install agent skills" href="./skill" icon="wand-magic-sparkles" />

  <Card title="agent - Coding-agent manual" href="./agent" icon="robot" />
</Columns>


# kill - Cancel operations
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/kill



<Note>
  **`contree kill` is a top-level shortcut for [operation cancel](./operation) (`contree op cancel`).**

  Both share one argparse setup and one handler. The top-level `kill`
  accepts the same positional UUIDs and `--all` flag as `op cancel`,
  including multiple UUIDs in a single invocation. See the
  [operation - Manage operations](./operation) page for the full description.
</Note>

Cancel running operations. Only active operations (PENDING, ASSIGNED,
EXECUTING) can be cancelled.

## Examples

```bash theme={null}
# Cancel a specific operation
contree kill 3f2a7b...

# Cancel multiple operations in one call
contree kill 3f2a7b... a1b2c3... 9d8e7f...

# Cancel all active operations
contree kill --all
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree kill --help</div></div><pre><code><span>usage: </span><span>contree kill</span><span> \[</span><span>-h</span><span>] \[</span><span>-a</span><span>] </span><span>\[UUID\_OR\_REF ...]</span><br /><br /><span>Manage operations (list, inspect, cancel).</span><br /><br /><span>Aggregates ps/show/kill under a single namespace, and adds multi-UUID</span><br /><span>support to \`\`show\`\` and \`\`cancel\`\` so several operations can be acted</span><br /><span>on in one invocation.</span><br /><br /><span>Subcommands:</span><br /><span>  list (ls)             List operations. \`\`contree ps\`\` is an alias.</span><br /><span>  show UUID \[UUID...]   Show one or more operation results.</span><br /><span>  cancel UUID \[UUID...] Cancel one or more operations (or --all).</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>UUID\_OR\_REF</span><span>  Operations to cancel. Accepts UUIDs and session-history references (HEAD, HEAD\~N,</span><br /><span>               @, @N, @-N, @+N, :N, bare N).</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>   show this help message and exit</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>    Cancel every active operation</span><br /><br /><span>for coding agents:</span><br /><span>  list/show are read-only; cancel mutates remote state</span><br /><span>  show and cancel accept multiple UUIDs in one invocation</span><br /><span>  show supports @N session-history references inherited from \`contree show\`</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

The CLI sends a `DELETE` request to the API for each UUID. The
operation transitions to `CANCELLED` status. If the sandbox is already
running, execution is interrupted.

`--all` finds and cancels every active operation in the project. When
`--all` is combined with explicit UUIDs, `--all` wins and the explicit
UUIDs are ignored with a `WARNING`.

On per-UUID API errors (e.g. 404 for an unknown UUID), the command
logs the failure and continues with the remaining UUIDs, exiting with
status `1` at the end.

## See also

* [operation - Manage operations](./operation) — the canonical command (`contree kill` is its shortcut)
* [ps - List activity](./ps) — list operations to find UUIDs
* [run - Execute a command in the sandbox](./run) — Ctrl-C during `contree run` also cancels the operation


# ls - List files in the image
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/ls



List files and directories in the session image without spawning a sandbox.

## Examples

```bash theme={null}
# List root directory
contree ls /

# List a specific directory
contree ls /etc/nginx

# JSON output with file metadata
contree -o json ls /usr/bin
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree ls --help</div></div><pre><code><span>usage: </span><span>contree ls</span><span> \[</span><span>-h</span><span>] </span><span>\[path]</span><br /><br /><span>List files in the session image.</span><br /><br /><span>Uses the /inspect/ API to list directory contents without spawning an</span><br /><span>instance. Defaults to the session working directory (set via \`cd\`).</span><br /><br /><span>In default format, the API returns a pre-formatted text listing. In</span><br /><span>structured formats (json, csv, etc.) the response is cached per</span><br /><span>(image, path) for instant repeat queries.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>path</span><span>        Path inside image (defaults to session cwd)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  read-only command (inspect API, no instance spawn)</span><br /><span>  defaults to session cwd when PATH is omitted</span><br /><span>  use -o json for cacheable structured listings</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Output

Each entry shows path, size, permissions (octal), owner, group, modification
time, and type (`d` for directory, `l` for symlink, `-` for file).

This command reads the image filesystem directly – no sandbox is started and
no resources are consumed.

## See also

* [cat - Show file content from the image](./cat) – view file contents
* [cp - Download a file from the image](./cp) – download a file locally
* [Your First Sandbox](../tutorial/first-steps) – inspecting the filesystem


# operation - Manage operations
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/operation



Manage operations under a single namespace. Aggregates `ps` (list),
`show` (inspect), and `kill` (cancel), and adds **multi-UUID support** to
`show` and `cancel` so several operations can be acted on in one call.

`op` is the short alias.

## Subcommands

| Subcommand              | Aliases     | Description                                                  |
| ----------------------- | ----------- | ------------------------------------------------------------ |
| `list`                  | `ls`        | List operations. Same flags as `contree ps`.                 |
| `show UUID [UUID...]`   | `sh`        | Show one or more operation results.                          |
| `wait UUID [UUID...]`   | `w`         | Wait for operations to reach a terminal status (or `--all`). |
| `cancel UUID [UUID...]` | `kill`, `k` | Cancel one or more operations (or `--all`).                  |

## Examples

```bash theme={null}
# List active operations (same as `contree ps`)
contree op list
contree op ls
contree op ls -a --status FAILED # all flags from ps are accepted

# Inspect a single operation
contree op show 3f2a7b...

# Inspect several operations at once
contree op show 3f2a7b... a1b2c3... 9d8e7f...

# History references (inherited from `contree show`)
contree op show @5 @4 @3

# Cancel one or more operations
contree op cancel 3f2a7b...
contree op cancel a1b2c3... 9d8e7f...

# Cancel every active operation
contree op cancel --all
```

## Help output

The top-level `op` command is a dispatcher: by itself it only prints
usage and routes to the three subcommands described below.

<div><div><div><span /><span /><span /></div><div>\$ contree op --help</div></div><pre><code><span>usage: </span><span>contree operation</span><span> \[</span><span>-h</span><span>] </span><span>\{list,ls,show,sh,cancel,kill,k,wait,w} ...</span><br /><br /><span>Manage operations (list, inspect, cancel).</span><br /><br /><span>Aggregates ps/show/kill under a single namespace, and adds multi-UUID</span><br /><span>support to \`\`show\`\` and \`\`cancel\`\` so several operations can be acted</span><br /><span>on in one invocation.</span><br /><br /><span>Subcommands:</span><br /><span>  list (ls)             List operations. \`\`contree ps\`\` is an alias.</span><br /><span>  show UUID \[UUID...]   Show one or more operation results.</span><br /><span>  cancel UUID \[UUID...] Cancel one or more operations (or --all).</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{list,ls,show,sh,cancel,kill,k,wait,w}</span><br /><span>    </span><span>list (ls)</span><span>           List operations</span><br /><span>    </span><span>show (sh)</span><span>           Show one or more operation results</span><br /><span>    </span><span>cancel (kill, k)</span><span>    Cancel one or more operations</span><br /><span>    </span><span>wait (w)</span><span>            Wait for operations to reach a terminal status</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  list/show are read-only; cancel mutates remote state</span><br /><span>  show and cancel accept multiple UUIDs in one invocation</span><br /><span>  show supports @N session-history references inherited from \`contree show\`</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## `op list` – dynamic columns

`contree op list` (alias `op ls`) accepts the same filter flags as
`contree ps` (`-a`, `--status STATUS`, `-K KIND`, `--since`,
`--until`, `-q`/`--quiet`) and shares its rendering pipeline. Reach
for it when you want the operations namespace to feel symmetric with
the multi-UUID `show` and `cancel`; otherwise `contree ps` is just
as good. `-S` is the global session flag and only works BEFORE the
subcommand.

<div><div><div><span /><span /><span /></div><div>\$ contree op list --help</div></div><pre><code><span>usage: </span><span>contree operation list</span><span> \[</span><span>-h</span><span>] \[</span><span>-q</span><span>] \[</span><span>-a</span><span>]</span><br /><span>                              \[</span><span>--status </span><span>\{P,PENDING,A,ASSIGNED,E,EXECUTING,S,SUCCESS,F,FAILED,C,CANCELLED}</span><span>]</span><br /><span>                              \[</span><span>-k </span><span>\{image\_import,instance}</span><span>] \[</span><span>--since </span><span>SINCE</span><span>] \[</span><span>--until </span><span>UNTIL</span><span>]</span><br /><span>                              \[</span><span>-M </span><span>SHOW\_MAX</span><span>]</span><br /><br /><span>List operations. \`\`contree ps\`\` is an alias of this command.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>-q</span><span>, </span><span>--quiet</span><span>           Only show UUIDs, useful for scripting</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>             Show all operations (default: active only)</span><br /><span>  </span><span>--status</span><span> </span><span>\{P,PENDING,A,ASSIGNED,E,EXECUTING,S,SUCCESS,F,FAILED,C,CANCELLED}</span><br /><span>                        Filter by status (default: EXECUTING only, unless -a is used)</span><br /><span>  </span><span>-k</span><span>, </span><span>--kind</span><span> </span><span>\{image\_import,instance}</span><br /><span>                        Filter by operation kind</span><br /><span>  </span><span>--since</span><span> </span><span>SINCE</span><span>         Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.</span><br /><span>  </span><span>--until</span><span> </span><span>UNTIL</span><span>         Show operations before. Parse +/- intervals (bare seconds or smhdMy) or</span><br /><span>                        ISO/date to UTC datetime.</span><br /><span>  </span><span>-M</span><span>, </span><span>--show-max</span><span> </span><span>SHOW\_MAX</span><br /><span>                        Show at most this many operations, useful for --all with large history</span><br /><span>                        (default: 1000)</span><br /><br /><span>for coding agents: read-only command</span></code></pre></div>

The listing renders **every scalar top-level field** the API returns,
not a hard-coded subset. When the server adds a new field (for example
`cost`, `project_id`, `started_at`), it appears in the output without a
CLI release. Nested structures (`metadata`, `result`, `tags`) are
filtered out – use `op show UUID` for the detail view.

Known fields are lightly typed:

| Field                                                   | Transform                                          |
| ------------------------------------------------------- | -------------------------------------------------- |
| `created_at`, `started_at`, `finished_at`, `updated_at` | parsed to UTC datetime                             |
| `duration`                                              | wrapped as `timedelta` (`total_seconds()` in JSON) |
| `error`                                                 | `None` is rendered as empty string                 |

Column order follows the API response, with one exception: **`error`
is pinned to the last column**. Long free-form error messages would
otherwise push the rest of the row out of alignment.

## `op show` – multiple UUIDs

Each UUID is fetched and rendered through the same code path as
`contree show`, so cached terminal results and history references work
uniformly. Accepted reference forms (mirroring `session rollback`
syntax with a git-style alias):

* `@`, `:`, or `HEAD` – the operation at the active branch tip.
* `@N` (or `:N`, bare `N`) – absolute history id.
* `@-N`, `:-N`, or `HEAD~N` – walk N steps back from the tip.
* `HEAD~` – shorthand for `HEAD~1`.
* `@+N` (or `:+N`) – walk N steps forward from the tip, picking the
  latest child at each branch point.

On API errors (e.g. 404 for an unknown UUID), the command logs the
failure and continues with the remaining UUIDs, exiting with status
`1` at the end.

<div><div><div><span /><span /><span /></div><div>\$ contree op show --help</div></div><pre><code><span>usage: </span><span>contree operation show</span><span> \[</span><span>-h</span><span>] \[</span><span>--raw</span><span>] </span><span>UUID\_OR\_REF \[UUID\_OR\_REF ...]</span><br /><br /><span>Fetch and display the result of each given operation. Same per-UUID behaviour as \`contree show\`:</span><br /><span>terminal results are cached; @N references resolve against session history.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>UUID\_OR\_REF</span><span>  Operations to inspect. Accepts UUIDs and session-history references: @ or HEAD for</span><br /><span>               the active branch tip, @N for an absolute history id, @-N or HEAD\~N for N steps</span><br /><span>               back, @+N for N steps forward.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>   show this help message and exit</span><br /><span>  </span><span>--raw</span><span>        Print each operation's JSON payload as JSONL (one object per line) to stdout.</span><br /><span>               Round-trips through the typed operation model, so fields the model doesn't know</span><br /><span>               about are dropped. Skips formatter routing and derived columns; streams cleanly</span><br /><span>               into \`jq -c\`. Useful for debugging or for fields the table view omits.</span><br /><br /><span>for coding agents: read-only command accepts multiple UUIDs; each rendered as its own row</span></code></pre></div>

<Note>
  With table output (`-o table`) and several UUIDs, each operation
  currently renders as its own mini-table. Use `default` or `json` for a
  unified stream view across multiple UUIDs.
</Note>

## `op wait` – block until completion

Poll the given operations until each reaches a terminal status
(`SUCCESS`, `FAILED`, `CANCELLED`) and print one row per completion
with the columns `uuid`, `status`, `exit_code`, `timed_out`,
`duration` (and every other scalar field the API returns; `error` is
pinned to the last column).

`--all` waits for every currently active operation in the project.
`--timeout SECONDS` (default `60`) caps the wait — when the deadline
hits, the command emits one extra row per unfinished operation with
`timed_out=true` and the operation’s last observed status (e.g.
`EXECUTING`), then exits with status `1`.

`status` is the server’s word: it reflects orchestration (did the
API run the job?), not what the sandbox process did with its exit
code. The exit code is a separate column. The CLI’s own exit status
is `1` whenever any operation finished non-`SUCCESS`, or the actual
`exit_code` when a `SUCCESS` op exited non-zero — so
`op wait UUID && next-step` composes correctly with sandbox commands
like `run -- false`.

<Info>
  `op wait` is a **pure observer**: it polls operation status and
  prints rows, but it **never updates session state**. In particular,
  the `detached-<op-uuid>` branch created when you ran
  `contree run -d` keeps pointing at the **starting** image — `op wait` does not advance it to the result image. The pattern therefore
  fits non-image-producing runs (`--disposable`) most cleanly; for
  non-disposable fan-out, the result image of each leg lives only on
  the server and you must recover it explicitly (see the non-disposable
  example below).
</Info>

<Warning>
  `--all` is **project-scoped**. If multiple agents (or multiple shell
  sessions) share the same project, `op wait --all` will block on every
  active operation across all of them — not just the ones you launched.
  The wait still completes correctly; it just waits for more than you
  might expect. For multi-agent setups, prefer the explicit
  `op wait UUID1 UUID2 ...` form with the UUIDs you actually own.
</Warning>

<div><div><div><span /><span /><span /></div><div>\$ contree op wait --help</div></div><pre><code><span>usage: </span><span>contree operation wait</span><span> \[</span><span>-h</span><span>] \[</span><span>-a</span><span>] \[</span><span>-t </span><span>TIMEOUT</span><span>] </span><span>\[UUID\_OR\_REF ...]</span><br /><br /><span>Poll the given operations until each reaches a terminal status (SUCCESS, FAILED, CANCELLED) and</span><br /><span>print one row per completion. With --all, waits for every currently active operation (PENDING,</span><br /><span>ASSIGNED, EXECUTING).</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>UUID\_OR\_REF</span><span>           Operations to wait for. Accepts UUIDs and session-history references</span><br /><span>                        (HEAD, HEAD\~N, @, @N, @-N, @+N, :N, bare N).</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>             Wait for every active operation</span><br /><span>  </span><span>-t</span><span>, </span><span>--timeout</span><span> </span><span>TIMEOUT</span><br /><span>                        Fail with exit code 1 if not all operations reach a terminal status within</span><br /><span>                        this many seconds (default: 60)</span><br /><br /><span>for coding agents: read-only command (polls the API; no state mutation) fails with exit code 1 if</span><br /><span>--timeout is hit before all complete exit code 1 also when any operation finished non-SUCCESS</span></code></pre></div>

Preferred — `--disposable` fan-out, no image to track. Note the
global `-o json` before `run` so `jq` sees JSON; the default
formatter is plain.

```bash theme={null}
A=$(contree -o json run -d --disposable -- pytest tests/a | jq -r .uuid)
B=$(contree -o json run -d --disposable -- pytest tests/b | jq -r .uuid)
C=$(contree -o json run -d --disposable -- pytest tests/c | jq -r .uuid)
contree op wait "$A" "$B" "$C"
contree op show "$A" "$B" "$C"          # stdout/stderr per leg
```

Non-disposable fan-out — must recover the chosen leg’s image yourself:

```bash theme={null}
A=$(contree -o json run -d -- apt-get install -y curl | jq -r .uuid)
B=$(contree -o json run -d -- apt-get install -y wget | jq -r .uuid)
contree op wait "$A" "$B"

# Pull the result image out and bind it back into the session,
# or tag it for later reuse.
IMG_A=$(contree -o json op show "$A" | jq -r .image)
contree use "$IMG_A"
contree tag "$IMG_A" feature/curl-tools
```

Block on the whole project (5 min cap):

```bash theme={null}
contree op wait --all --timeout 300
```

## `op cancel` – multiple UUIDs or `--all`

Either pass UUIDs explicitly or use `--all` to cancel every active
operation (`PENDING`, `ASSIGNED`, `EXECUTING`). Combining both is allowed:
`--all` wins, and the explicit UUIDs are ignored with a `WARNING`. As
with `op show`, errors on individual UUIDs do not abort the run; the
command exits `1` if any cancellation failed.

<div><div><div><span /><span /><span /></div><div>\$ contree op cancel --help</div></div><pre><code><span>usage: </span><span>contree operation cancel</span><span> \[</span><span>-h</span><span>] \[</span><span>-a</span><span>] </span><span>\[UUID\_OR\_REF ...]</span><br /><br /><span>Cancel each given operation. With --all, cancels every active operation (PENDING, ASSIGNED,</span><br /><span>EXECUTING).</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>UUID\_OR\_REF</span><span>  Operations to cancel. Accepts UUIDs and session-history references (HEAD, HEAD\~N,</span><br /><span>               @, @N, @-N, @+N, :N, bare N).</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>   show this help message and exit</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>    Cancel every active operation</span><br /><br /><span>for coding agents: mutating command pass UUIDs to cancel specific operations or --all for</span><br /><span>everything</span></code></pre></div>

```bash theme={null}
# Mixed: --all still wins, "ignored-1" is not cancelled
contree op cancel --all ignored-1
```

## Comparison with the top-level commands

`contree ps` and `contree kill` are top-level **shortcuts** that share
the same argparse setup and handler as `op list` / `op cancel`
respectively — there is no separate implementation. `contree show`
keeps its own single-UUID handler (the multi-UUID `op show` wraps it).

| Need                       | Use                                                                     |
| -------------------------- | ----------------------------------------------------------------------- |
| List active operations     | `contree ps` *or* `contree op ls`                                       |
| Inspect one operation      | `contree show UUID` *or* `contree op show UUID`                         |
| Inspect multiple           | `contree op show UUID1 UUID2 ...`                                       |
| Block on multiple          | `contree op wait UUID1 UUID2 ...`                                       |
| Block on everything active | `contree op wait --all`                                                 |
| Cancel one operation       | `contree kill UUID` *or* `contree op cancel UUID`                       |
| Cancel multiple            | `contree kill UUID1 UUID2 ...` *or* `contree op cancel UUID1 UUID2 ...` |
| Cancel everything active   | `contree kill --all` *or* `contree op cancel --all`                     |

## See also

* [ps - List activity](./ps) – top-level shortcut for `op list`
* [show - Inspect an operation](./show) – single-UUID inspect (delegated to by `op show`)
* [kill - Cancel operations](./kill) – top-level shortcut for `op cancel`
* [run - Execute a command in the sandbox](./run) – the command that creates operations


# ps - List activity
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/ps



<Note>
  **`contree ps` is a top-level shortcut for [operation list](./operation) (`contree op ls`).**

  Both share one argparse setup and one handler — `ps` exists for the
  Docker-like UX. New flags or columns added to `operation list` apply
  automatically here. See the [operation - Manage operations](./operation) page for the full
  description of dynamic columns, error handling, and multi-UUID
  workflows in the operation namespace.
</Note>

List operations and their statuses. By default shows only active operations
(PENDING, ASSIGNED, EXECUTING).

## Examples

```bash theme={null}
# Show active operations
contree ps

# Show all operations (including completed)
contree ps -a

# UUIDs only (for scripting)
contree ps -q

# Filter by status (note: --status, not -S; -S is the global session flag)
contree ps --status FAILED

# Filter by kind
contree ps -k instance

# Operations from the last hour
contree ps -a --since=1h

# Pipe to other commands
contree ps -q | xargs -I {} contree show {}
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree ps --help</div></div><pre><code><span>usage: </span><span>contree ps</span><span> \[</span><span>-h</span><span>] \[</span><span>-q</span><span>] \[</span><span>-a</span><span>]</span><br /><span>                  \[</span><span>--status </span><span>\{P,PENDING,A,ASSIGNED,E,EXECUTING,S,SUCCESS,F,FAILED,C,CANCELLED}</span><span>]</span><br /><span>                  \[</span><span>-k </span><span>\{image\_import,instance}</span><span>] \[</span><span>--since </span><span>SINCE</span><span>] \[</span><span>--until </span><span>UNTIL</span><span>] \[</span><span>-M </span><span>SHOW\_MAX</span><span>]</span><br /><br /><span>Manage operations (list, inspect, cancel).</span><br /><br /><span>Aggregates ps/show/kill under a single namespace, and adds multi-UUID</span><br /><span>support to \`\`show\`\` and \`\`cancel\`\` so several operations can be acted</span><br /><span>on in one invocation.</span><br /><br /><span>Subcommands:</span><br /><span>  list (ls)             List operations. \`\`contree ps\`\` is an alias.</span><br /><span>  show UUID \[UUID...]   Show one or more operation results.</span><br /><span>  cancel UUID \[UUID...] Cancel one or more operations (or --all).</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>-q</span><span>, </span><span>--quiet</span><span>           Only show UUIDs, useful for scripting</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>             Show all operations (default: active only)</span><br /><span>  </span><span>--status</span><span> </span><span>\{P,PENDING,A,ASSIGNED,E,EXECUTING,S,SUCCESS,F,FAILED,C,CANCELLED}</span><br /><span>                        Filter by status (default: EXECUTING only, unless -a is used)</span><br /><span>  </span><span>-k</span><span>, </span><span>--kind</span><span> </span><span>\{image\_import,instance}</span><br /><span>                        Filter by operation kind</span><br /><span>  </span><span>--since</span><span> </span><span>SINCE</span><span>         Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.</span><br /><span>  </span><span>--until</span><span> </span><span>UNTIL</span><span>         Show operations before. Parse +/- intervals (bare seconds or smhdMy) or</span><br /><span>                        ISO/date to UTC datetime.</span><br /><span>  </span><span>-M</span><span>, </span><span>--show-max</span><span> </span><span>SHOW\_MAX</span><br /><span>                        Show at most this many operations, useful for --all with large history</span><br /><span>                        (default: 1000) (default: 1000)</span><br /><br /><span>for coding agents:</span><br /><span>  list/show are read-only; cancel mutates remote state</span><br /><span>  show and cancel accept multiple UUIDs in one invocation</span><br /><span>  show supports @N session-history references inherited from \`contree show\`</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Operation statuses

| Status      | Meaning                       |
| ----------- | ----------------------------- |
| `PENDING`   | Queued, waiting for resources |
| `ASSIGNED`  | Assigned to a worker          |
| `EXECUTING` | Running                       |
| `SUCCESS`   | Completed successfully        |
| `FAILED`    | Completed with an error       |
| `CANCELLED` | Cancelled by the user         |

Without `-a`, only `PENDING`, `ASSIGNED`, and `EXECUTING` are shown.

## Dynamic output columns

`ps` renders every scalar top-level field the API returns (not a fixed
subset), so new server fields appear automatically. `error` is pinned
to the last column. See [operation - Manage operations](./operation) for the full description.

## See also

* [operation - Manage operations](./operation) — the canonical command (`contree ps` is its shortcut)
* [show - Inspect an operation](./show) — inspect a specific operation
* [kill - Cancel operations](./kill) — cancel a running operation
* [Scripting & Automation](../tutorial/workflows) — monitoring and scripting patterns


# run - Execute a command in the sandbox
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/run



Spawn a sandbox instance from the session image and execute a command.

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree run --help</div></div><pre><code><span>usage: </span><span>contree run</span><span> \[</span><span>-h</span><span>] \[</span><span>-t </span><span>TIMEOUT</span><span>] \[</span><span>-C </span><span>CWD</span><span>] \[</span><span>-e </span><span>ENV</span><span>] \[</span><span>-H </span><span>HOSTNAME</span><span>] \[</span><span>-D</span><span>] \[</span><span>-I</span><span>] \[</span><span>-s</span><span>] \[</span><span>-F </span><span>FILE</span><span>]</span><br /><span>                   \[</span><span>--file-excludes </span><span>PATTERN \[PATTERN ...]</span><span>] \[</span><span>-T </span><span>TRUNCATE</span><span>] \[</span><span>--preserve-env</span><span>] \[</span><span>-d</span><span>]</span><br /><span>                   \[</span><span>--use </span><span>IMAGE</span><span>]</span><br /><span>                   </span><span>...</span><br /><br /><span>Spawn a sandbox instance from the current session image and execute a command.</span><br /><br /><span>Uses the image from the active session (set via \`contree use IMAGE\`),</span><br /><span>or an image specified inline via \`\`--use IMAGE\`\`.</span><br /><span>Commands are passed after -- separator; without --, the first</span><br /><span>positional arg is the command.</span><br /><br /><span>By default the CLI polls until the operation reaches a terminal</span><br /><span>status (SUCCESS, FAILED, CANCELLED) and prints stdout/stderr.</span><br /><span>Use -d/--detach to exit immediately after spawning.</span><br /><br /><span>File attachments:</span><br /><span>  Use --file to inject host files or directories into the sandbox</span><br /><span>  before execution. Files are uploaded to the API (with SHA256 dedup)</span><br /><span>  and mounted at the specified instance path. Ownership and</span><br /><span>  permissions default to host file stat unless overridden.</span><br /><br /><span>  Note: non-disposable runs persist filesystem changes into a</span><br /><span>  new image. Files attached once are already part of that image</span><br /><span>  and do not need re-attachment. Use --disposable to discard</span><br /><span>  changes after execution.</span><br /><br /><span>  Format: host\_path\[:instance\_path]\[:uUID]\[:gGID]\[:mMODE]</span><br /><br /><span>    host\_path                             all defaults from stat</span><br /><span>    host\_path:/inst/path                  point a destination path</span><br /><span>    host\_path:m0755                       override only mode</span><br /><span>    host\_path:/inst/path:u0:g0:m0755      all explicit</span><br /><span>    host\_path:uroot:groot                 uid/gid by name (local)</span><br /><br /><span>  Tagged options (u/g/m) can appear in any order after host\_path.</span><br /><span>  instance\_path is detected by its leading /.</span><br /><span>  For directory attachments, files are walked recursively and default</span><br /><span>  excludes are applied: .\*, .git, \*.pyc, \_\_pycache\_\_, .venv,</span><br /><span>  .mypy\_cache, .pytest\_cache, node\_modules, dist, build.</span><br /><span>  Add extra patterns with --file-excludes.</span><br /><br /><span>  The CLI also keeps a local upload cache keyed by</span><br /><span>  path+inode+mtime+size and reuses known file UUIDs to avoid</span><br /><span>  unnecessary re-upload checks/uploads.</span><br /><br /><span>  Note: named uid/gid (e.g. uroot) are resolved locally via</span><br /><span>  pwd/grp — use numeric IDs if unsure about host/sandbox mismatch.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>command\_args</span><span>          Command and arguments (after --)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>-t</span><span>, </span><span>--timeout</span><span> </span><span>TIMEOUT</span><br /><span>                        Timeout in seconds (default: 120)</span><br /><span>  </span><span>-C</span><span>, </span><span>--cwd</span><span> </span><span>CWD</span><span>         Working directory inside sandbox, absolute path or empty string for use</span><br /><span>                        sandbox WORKDIR (default: )</span><br /><span>  </span><span>-e</span><span>, </span><span>--env</span><span> </span><span>ENV</span><span>         Environment variable KEY=VALUE (repeatable)</span><br /><span>  </span><span>-H</span><span>, </span><span>--hostname</span><span> </span><span>HOSTNAME</span><br /><span>                        Container hostname (default: linuxkit)</span><br /><span>  </span><span>-D</span><span>, </span><span>--disposable</span><span>      Drop filesystem changes after run</span><br /><span>  </span><span>-I</span><span>, </span><span>--interpreter</span><span>     Interpreter (shebang) mode. Read the script file given as the first</span><br /><span>                        argument, strip the #! line, and send the body as stdin to /bin/sh -s.</span><br /><span>                        Usage: #!/usr/bin/env -S contree run -I</span><br /><span>  </span><span>-s</span><span>, </span><span>--shell</span><span>           Join command args into a single shell expression</span><br /><span>  </span><span>-F</span><span>, </span><span>--file</span><span> </span><span>FILE</span><span>       Attach file or directory (repeatable, dirs recurse). Format:</span><br /><span>                        host\[:inst\_path]\[:uUID]\[:gGID]\[:mMODE]. Tagged options (u/g/m) in any</span><br /><span>                        order; uid/gid resolved locally from pwd/grp; defaults from host stat.</span><br /><span>  </span><span>--file-excludes</span><span> </span><span>PATTERN \[PATTERN ...]</span><br /><span>                        Additional glob exclude patterns for directory attachments (repeatable).</span><br /><span>  </span><span>-T</span><span>, </span><span>--truncate</span><span> </span><span>TRUNCATE</span><br /><span>                        Truncate output to N bytes (default: 65536)</span><br /><span>  </span><span>--preserve-env</span><span>        Preserve env vars from previous run (server-side)</span><br /><span>  </span><span>-d</span><span>, </span><span>--detach</span><span>, </span><span>--no-wait</span><br /><span>                        Exit immediately after spawning (do not wait for result)</span><br /><span>  </span><span>--use</span><span> </span><span>IMAGE</span><span>           Switch session to IMAGE before running (UUID or tag:NAME). Equivalent to</span><br /><span>                        'contree use IMAGE' followed by 'run'. Recorded in session history and can</span><br /><span>                        be rolled back with 'session rollback'. (default: )</span><br /><br /><span>examples:</span><br /><span>  contree use ubuntu && contree run -- uname -a</span><br /><span>  contree run --use tag:ubuntu:latest -- uname -a</span><br /><span>  contree run --shell -- 'echo hello && ls /'</span><br /><span>  contree run -e FOO=bar DEBUG=1 -- ./app</span><br /><span>  contree run --file ./app.py:/app.py --disposable -- python /app.py</span><br /><span>  contree run --file ./src:/app/src --file-excludes '\*.log' -- make -C /app/src</span><br /><span>  contree run -d -- sleep 3600</span><br /><br /><span>for coding agents:</span><br /><span>  \`run\` executes remotely inside the instance image (not on local host)</span><br /><span>  local files/dirs must be mapped with --file to be available remotely</span><br /><span>  mutates session image unless --disposable is set</span><br /><span>  supports directory attachments via --file host\_dir:/instance\_dir</span><br /><span>  local file cache avoids re-upload when path+inode+mtime+size unchanged</span><br /><span>  returns command exit code when available</span><br /><span>  default formatter prints raw stdout/stderr only</span><br /><span>  use -o json for structured operation metadata</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Quick start with `--use`

Switch session to an image and run a command in one step:

```bash theme={null}
contree run --use tag:ubuntu:latest -- uname -a
```

This is equivalent to:

```bash theme={null}
contree use tag:ubuntu:latest
contree run -- uname -a
```

The image switch is recorded in session history and can be rolled back
with `contree session rollback`.

## Execution modes

**Direct command** (default):

```bash theme={null}
contree run uname -a
```

**Shell mode** (`-s` / `--shell`):

```bash theme={null}
contree run -s -- 'echo hello && ls /'
```

Joins all command args into a single shell expression.

**Interpreter mode** (`-I` / `--interpreter`):

```bash theme={null}
contree run -I ./script.sh
```

Reads a local script, strips the `#!` line, and sends the body as stdin
to `/bin/sh -s`. Enables shebang scripts:

```bash theme={null}
#!/usr/bin/env -S contree run -I
echo "runs inside a ConTree sandbox"
```

**Piped stdin**:

```bash theme={null}
echo 'uname -a' | contree run /bin/sh
```

When stdin is not a TTY, it is read, base64-encoded, and sent as the
`stdin` field.

## Lifecycle

1. Resolve the session image (or switch to `--use IMAGE` first)
2. Upload any `--file` attachments (with SHA256 dedup)
3. Merge pending files from `contree file edit`/`cp`
4. POST `/v1/instances`
5. Poll until terminal status (unless `-d`)
6. Print stdout/stderr; propagate the exit code

On Ctrl-C the operation is cancelled via DELETE.

See [Working with Files](../tutorial/files) for `--file` syntax details.


# session - Manage sessions, branches, history
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/session



Manage session branches and history. Sessions track the image state as you
run commands, with support for branching and rollback.

## Examples

```bash theme={null}
# Show current session
contree session

# List all sessions
contree session list

# Show full history
contree session show

# Create and switch to a branch
contree session branch experiment
contree session checkout experiment

# Switch back
contree session checkout main

# Create a branch from another branch
contree session branch hotfix --from main

# List branches (* marks active)
contree session branch

# Undo last operation
contree session rollback

# Undo last 3 operations (`--` stops argparse from eating `-3` as a flag)
contree session rollback -- -3

# Forward one entry
contree session rollback +1

# Absolute jump to a specific history id (use `session show` first)
contree session rollback 42

# Import image from another session
contree session use other-session

# Delete a session
contree session delete my-old-session
contree session rm my-old-session -y
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree session --help</div></div><pre><code><span>usage: </span><span>contree session</span><span> \[</span><span>-h</span><span>]</span><br /><span>                       </span><span>\{list,ls,use,branch,br,checkout,co,rollback,rb,show,wait,delete,rm,del} ...</span><br /><br /><span>Manage session branches and history.</span><br /><br /><span>Without a subcommand, shows the current session info (key, branch,</span><br /><span>image, last operation).</span><br /><br /><span>Subcommands:</span><br /><span>  list (ls)       List all sessions</span><br /><span>  use KEY         Import another session's current image</span><br /><span>  branch (br)     List or create branches (--from to fork)</span><br /><span>  checkout (co)   Switch active branch</span><br /><span>  rollback (rb)   Navigate history: N=absolute, -N=back, +N=forward</span><br /><span>  show            Display the session history DAG</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{list,ls,use,branch,br,checkout,co,rollback,rb,show,wait,delete,rm,del}</span><br /><span>    </span><span>list (ls)</span><span>           List all sessions</span><br /><span>    </span><span>use</span><span>                 Import another session's image</span><br /><span>    </span><span>branch (br)</span><span>         List, create, delete, or prune branches</span><br /><span>    </span><span>checkout (co)</span><span>       Switch active branch</span><br /><span>    </span><span>rollback (rb)</span><span>       Navigate history: N=absolute, -N=back, +N=forward</span><br /><span>    </span><span>show</span><span>                Show session history</span><br /><span>    </span><span>wait</span><span>                Drain detached ops in the current session</span><br /><span>    </span><span>delete (rm, del)</span><span>    Delete sessions by key</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  session (no subcommand) is read-only</span><br /><span>  branch/checkout/rollback/session use mutates local session pointers</span><br /><span>  \`session show\` defaults to last 20 history entries; pass -a/--all for full DAG</span><br /><span>  use \`session show\` to inspect history DAG before destructive navigation</span><br /><span>  \`session wait \[OPS...]\` waits for active or specified operations</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Concepts

Each non-disposable `contree run` creates a new history entry and advances
the branch pointer. Branches share the underlying history – creating a
branch just adds a new pointer at the current position.

Rollback moves the branch pointer backwards. History entries are preserved
and can be recovered by creating a new branch.

## Subcommands

### `session list`

`contree session list` (alias `ls`) prints every session known to the
current profile, with the active session marked. The optional
`--filter` flag narrows the list by substring match against the session
key, which is handy when you keep many disposable sessions named after
features or tickets.

<div><div><div><span /><span /><span /></div><div>\$ contree session list --help</div></div><pre><code><span>usage: </span><span>contree session list</span><span> \[</span><span>-h</span><span>] \[</span><span>--filter </span><span>FILTER\_TEXT</span><span>]</span><br /><br /><span>List locally known sessions and their current branch/image.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><span>  </span><span>--filter</span><span> </span><span>FILTER\_TEXT</span><span>  Filter session keys containing this text</span><br /><br /><span>for coding agents: read-only command</span></code></pre></div>

### `session use`

`contree session use KEY` imports the **current image** of another
session into the active session as a new history entry. The source
session is not modified; this is a “fork the snapshot, keep working
here” operation, distinct from the top-level `contree use` which starts
or resumes a session against an image reference.

<div><div><div><span /><span /><span /></div><div>\$ contree session use --help</div></div><pre><code><span>usage: </span><span>contree session use</span><span> \[</span><span>-h</span><span>] </span><span>session\_name</span><br /><br /><span>Set current session image to another session's tip image. Accepts exact key or key suffix.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>session\_name</span><span>  Session key or suffix to match</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>    show this help message and exit</span><br /><br /><span>for coding agents: mutates current session history</span></code></pre></div>

### `session branch`

`contree session branch` (alias `br`) lists branches with `*` marking
the active one. Pass a name to create a new branch pointing at the
current history position, or combine with `--from BRANCH` to fork off a
different branch. The `-U`/`--prune` flag removes branches that no
longer reference live history.

<div><div><div><span /><span /><span /></div><div>\$ contree session branch --help</div></div><pre><code><span>usage: </span><span>contree session branch</span><span> \[</span><span>-h</span><span>] \[</span><span>--from </span><span>FROM\_BRANCH</span><span>] \[</span><span>-U</span><span>] \[</span><span>--prune</span><span>] </span><span>\[branch\_name]</span><br /><br /><span>List branches (no args). Create with NAME (optionally --from). Delete with --delete NAME. Prune</span><br /><span>disposable-/detached- branches with --prune.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>branch\_name</span><span>         Branch name (create/delete target)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>          show this help message and exit</span><br /><span>  </span><span>--from</span><span> </span><span>FROM\_BRANCH</span><span>  Source branch (default: active branch)</span><br /><span>  </span><span>-U</span><span>, </span><span>--delete</span><span>, </span><span>--rm</span><span>  Delete the specified branch (NAME required, must not be active)</span><br /><span>  </span><span>--prune</span><span>             Prune disposable-/detached- branches (non-active only)</span><br /><br /><span>for coding agents: read-only when NAME/--delete/--prune omitted mutating when</span><br /><span>creating/deleting/pruning</span></code></pre></div>

### `session checkout`

`contree session checkout BRANCH` (alias `co`) switches the active
branch pointer. Working directory, pending files, and the current
image are all reset to whatever the target branch currently points at,
so it is the safe way to bounce between parallel experiments.

<div><div><div><span /><span /><span /></div><div>\$ contree session checkout --help</div></div><pre><code><span>usage: </span><span>contree session checkout</span><span> \[</span><span>-h</span><span>] </span><span>checkout\_branch</span><br /><br /><span>Move current session to another existing branch tip.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>checkout\_branch</span><span>  Branch to switch to</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><br /><span>for coding agents: mutates active branch pointer</span></code></pre></div>

### `session rollback`

`contree session rollback [TARGET]` (alias `rb`) navigates the history
of the current branch. With no argument it steps back one entry; a
positive number jumps to that absolute history index, `-N` steps back
`N` entries, and `+N` steps forward. History entries are preserved –
rollback only moves the branch pointer.

<div><div><div><span /><span /><span /></div><div>\$ contree session rollback --help</div></div><pre><code><span>usage: </span><span>contree session rollback</span><span> \[</span><span>-h</span><span>] </span><span>\[target]</span><br /><br /><span>Move branch pointer in session history. Supports absolute ID, relative backward (-N), and forward</span><br /><span>(+N).</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>target</span><span>      History target: ID (absolute), -N (back), +N (forward) — use \`-- -N\` for negative</span><br /><span>              values</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents: mutates active branch history pointer</span></code></pre></div>

### `session show`

`contree session show` prints the session history DAG with one row per
entry, including operation IDs, image UUIDs, branch pointers, and
relative timestamps. Use `-a` to include hidden entries, `-k KIND` to
filter by entry kind (e.g. `run`, `cd`), and `-l LAST` to show only the
last N rows.

<div><div><div><span /><span /><span /></div><div>\$ contree session show --help</div></div><pre><code><span>usage: </span><span>contree session show</span><span> \[</span><span>-h</span><span>] \[</span><span>-a</span><span>] \[</span><span>-k </span><span>KIND</span><span>] \[</span><span>-l </span><span>LAST</span><span>] \[</span><span>--since </span><span>SINCE</span><span>] \[</span><span>--until </span><span>UNTIL</span><span>]</span><br /><span>                            </span><span>\[session\_name]</span><br /><br /><span>Print session history DAG entries and branch labels. By default shows last 20 entries; use</span><br /><span>-a/--all for full history.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>session\_name</span><span>     Session key or suffix (default: current session)</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><span>  </span><span>-a</span><span>, </span><span>--all</span><span>        Show full history (default: last 20 entries)</span><br /><span>  </span><span>-k</span><span>, </span><span>--kind</span><span> </span><span>KIND</span><span>  Filter history entries by kind (e.g., run, use, cd)</span><br /><span>  </span><span>-l</span><span>, </span><span>--last</span><span> </span><span>LAST</span><span>  Show last N entries after filtering</span><br /><span>  </span><span>--since</span><span> </span><span>SINCE</span><span>    Show entries since. Parse +/- intervals (bare seconds or smhdMy) or ISO/date to</span><br /><span>                   UTC datetime.</span><br /><span>  </span><span>--until</span><span> </span><span>UNTIL</span><span>    Show entries before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date</span><br /><span>                   to UTC datetime.</span><br /><br /><span>for coding agents: read-only command</span></code></pre></div>

### `session wait`

`contree session wait [OP_ID ...]` blocks until the specified operations
reach a terminal state (`SUCCESS`, `FAILED`, or `CANCELLED`). When no
IDs are given it waits for every active operation in the session, which
is the canonical way to drain background `contree run -d` jobs before
moving on.

<div><div><div><span /><span /><span /></div><div>\$ contree session wait --help</div></div><pre><code><span>usage: </span><span>contree session wait</span><span> \[</span><span>-h</span><span>] </span><span>\[UUID\_OR\_REF ...]</span><br /><br /><span>Drain detached operations in the current session. With no arguments, reads the session's pending-</span><br /><span>ops cache, polls each to a terminal status, and advances the active branch to each non-disposable</span><br /><span>result image (recording \`disposable-\<uuid>\` branches for disposable runs). With explicit UUIDs,</span><br /><span>this command degrades to a plain polling loop: it prints completion rows but does NOT touch the</span><br /><span>active branch, because the pending metadata is not loaded for explicit UUIDs.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>UUID\_OR\_REF</span><span>  Operations to wait for (default: all active in this session). Accepts UUIDs and</span><br /><span>               session-history references (HEAD, HEAD\~N, @, @N, @-N, @+N, :N, bare N).</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>   show this help message and exit</span><br /><br /><span>for coding agents: no-arg form mutates session history (advances active branch) UUID form is a</span><br /><span>pure polling observer if you need result images from explicit UUIDs, use \`op show UUID | jq -r</span><br /><span>.image\` and \`contree use\`</span></code></pre></div>

### `session delete`

`contree session delete KEY [KEY ...]` (aliases `rm`, `del`) removes
sessions and all their data – history, branches, pending files, shell
history. The command prompts before deleting unless `-y` is passed.
Use this to garbage-collect throwaway sessions; the disk savings on
the SQLite database can be substantial when many short-lived sessions
accumulate.

<div><div><div><span /><span /><span /></div><div>\$ contree session delete --help</div></div><pre><code><span>usage: </span><span>contree session delete</span><span> \[</span><span>-h</span><span>] \[</span><span>-f</span><span>] </span><span>KEY \[KEY ...]</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>KEY</span><span>              Session keys to delete</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><span>  </span><span>-f</span><span>, </span><span>-y</span><span>, </span><span>--force</span><span>  Do not ask for confirmation</span></code></pre></div>

```bash theme={null}
contree session delete KEY [KEY ...]
contree session rm KEY -y     # skip confirmation
contree session del KEY
```

## See also

* [Sessions, Branches & Rollback](../tutorial/sessions) – full tutorial on sessions, branches, and rollback
* [use - Choose an image for the session](./use) – start or resume a session


# shell - Interactive REPL
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/shell



Start an interactive REPL for managing sessions and running sandbox commands.

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree shell --help</div></div><pre><code><span>usage: </span><span>contree shell</span><span> \[</span><span>-h</span><span>]</span><br /><br /><span>Start an interactive shell session.</span><br /><br /><span>Launches a REPL where bare commands (e.g. \`apt install curl\`) are</span><br /><span>executed in the session sandbox via \`run --shell\`, and prefixed</span><br /><span>commands (e.g. \`contree ls /etc\`) are dispatched as management</span><br /><span>commands.</span><br /><br /><span>Built-in commands: cd, pwd, history, help, exit/quit.</span><br /><span>Tab completion for commands, flags, image paths, tags, and branches.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><br /><span>for coding agents:</span><br /><span>  bare commands are implicit \`contree run --shell\`</span><br /><span>  management commands must be prefixed with \`contree\`</span><br /><span>  exit with \`exit\`/\`quit\` or Ctrl-D</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Examples

```bash theme={null}
# Start the shell
contree shell

# Start with a specific output format
contree -o json shell

# Start with a named profile
contree --profile=personal shell
```

## Prompt

The prompt shows the current working directory:

```text theme={null}
contree:/> apt-get update -qq
contree:/app> python main.py
```

## Command dispatch

The shell recognises four types of input:

**Bare commands** — executed inside the sandbox as an implicit `contree run`
with `shell=True`:

```text theme={null}
apt-get install -y curl
echo hello && ls /
```

**Prefixed commands** — `contree ...` dispatches management commands through
the same argparse parser as the CLI:

```text theme={null}
contree ls /etc
contree session branch experiment
contree run -e DEBUG=1 -- ./app
```

**Builtins** – handled locally by the shell:

| Builtin                     | Description                                                   |
| --------------------------- | ------------------------------------------------------------- |
| `cd [PATH]`                 | Change working directory (`cd -` for previous)                |
| `pwd`                       | Print working directory                                       |
| `history [SEARCH]`          | Show command history, optionally filtered by substring        |
| `help [TOPIC]`              | Show help (optionally for a specific command)                 |
| `clear`                     | Clear the terminal screen                                     |
| `timeout DURATION CMD...`   | Run `CMD...` with the API operation timeout set to `DURATION` |
| `--format NAME` / `-f NAME` | Change output format (or show current if no argument)         |
| `exit` / `quit`             | Exit the shell (also Ctrl-D)                                  |

**Aliases** — bare names intercepted for convenience:

| Alias       | Equivalent                                    |
| ----------- | --------------------------------------------- |
| `ls [PATH]` | `contree ls [PATH]` (API inspect, no sandbox) |
| `cat PATH`  | `contree cat PATH` (API inspect, no sandbox)  |
| `vim PATH`  | `contree file edit PATH` (with `EDITOR=vim`)  |
| `vi PATH`   | `contree file edit PATH` (with `EDITOR=vi`)   |
| `nvim PATH` | `contree file edit PATH` (with `EDITOR=nvim`) |
| `nano PATH` | `contree file edit PATH` (with `EDITOR=nano`) |

<Note>
  `ls` and `cat` aliases fall back to running inside the sandbox when pending
  files exist or when args contain flags or glob characters.
</Note>

## Implicit run: shell-expression passthrough

Bare commands are forwarded to the sandbox as a single shell expression with
`shell=True`. The entire input line is sent verbatim to the remote `sh -c`,
so operators like `|`, `;`, `&&`, `||`, `>`, `<` are interpreted by the
remote shell exactly as typed:

```text theme={null}
contree:/> mount | grep cgroup
contree:/> echo 1 ; echo 2
contree:/> apt-get update && apt-get install -y curl
contree:/> uname -a > /tmp/info.txt
```

There is no local tokenize/rejoin step, so quoting is preserved:

```text theme={null}
contree:/> python3 -c "print('hello world')"
```

## `timeout` builtin

The shell recognises `timeout DURATION CMD...` and sets the server-side
operation timeout to `DURATION` instead of running the GNU `timeout` binary
inside the sandbox. The kill is enforced by the API, not by a wrapper
process, so the operation surfaces a warning when the limit is hit:

```text theme={null}
contree:/> timeout 30 apk add gcc
contree:/> timeout 5m make build
contree:/> timeout 1h python long_train.py
```

`DURATION` is an integer or decimal optionally followed by a unit suffix:

| Suffix | Meaning |
| ------ | ------- |
| (none) | Seconds |
| `s`    | Seconds |
| `m`    | Minutes |
| `h`    | Hours   |
| `d`    | Days    |

If `DURATION` is not a valid spec (for example `timeout --kill-after=5 30 cmd`
or `timeout --help`), the shell falls through and sends the line to the
sandbox unchanged, so the in-image `timeout` binary still handles advanced
flags.

When the limit is hit, the response carries `state.timed_out=true` and the
shell logs:

```text theme={null}
WARNING: Operation <uuid> timed out after 30s
```

## Tab completion

The shell provides context-aware tab completion for almost everything
except bare (implicit run) commands. Press Tab to complete:

| Context                             | What completes                      |
| ----------------------------------- | ----------------------------------- |
| Empty prompt                        | All commands, aliases, and builtins |
| `contree <TAB>`                     | Subcommand names                    |
| `contree CMD -<TAB>`                | Flags for that command              |
| `contree CMD --<TAB>`               | Long flags for that command         |
| `ls /etc/<TAB>`, `cat /etc/<TAB>`   | Sandbox file paths                  |
| `cd /us<TAB>`                       | Sandbox directory paths (dirs only) |
| `vim /etc/<TAB>`, `nano /etc/<TAB>` | Sandbox file paths                  |
| `contree use <TAB>`                 | Image UUIDs and `tag:NAME`          |
| `contree tag <TAB>`                 | Image UUIDs and `tag:NAME`          |
| `contree show <TAB>`                | Operation UUIDs                     |
| `contree kill <TAB>`                | Operation UUIDs                     |
| `contree session checkout <TAB>`    | Branch names                        |
| `contree session branch <TAB>`      | Branch names                        |
| `contree session use <TAB>`         | Session keys                        |
| `contree file edit <TAB>`           | Sandbox file paths                  |
| `help <TAB>`                        | All command and alias names         |

Path completions query the sandbox filesystem via the inspect API
and are cached persistently – subsequent completions for the same
directory are instant.

## History search

The `history` builtin takes an optional pattern and filters the
persisted history by case-insensitive substring:

```text theme={null}
contree:/> history                 # show every entry for this session
contree:/> history apt             # any line containing "apt"
contree:/> history 'contree '      # exact "contree " (with trailing space)
contree:/> history make            # any line containing "make"
```

History is per-session: searches see only the current `session_key`’s
entries. Up to 10,000 lines are kept; older lines are trimmed on save.

## Line continuation

A trailing `\` at the end of input triggers a `> ` continuation prompt,
just like traditional shells:

```text theme={null}
contree:/> ls \
> -alh \
> /sys
```

Backslash-newline pairs are removed to join the lines into a single
command (`ls -alh /sys`). Unclosed quotes also trigger continuation,
preserving the newline inside the quoted string.

## Limitations

* **No global flags on commands**: `--token`, `--url`, `--log-level` are
  not available inside the shell.
* **No local pipes or redirects**: `|`, `>`, `<` are passed as-is to the
  sandbox (works for remote commands, not for contree output).
* **No job control**: No `&`, `bg`, `fg`, or Ctrl-Z. Use `contree run -d`
  for background tasks.
* **Bare commands use defaults**: `--env`, `--file`, `--disposable`, and
  `--detach` require the explicit `contree run` prefix. The operation
  timeout has a shorthand: `timeout DURATION CMD...` (see above).
* **No `~` or glob expansion**: Passed as-is to the sandbox.
* **Cannot nest shells**: Running `contree shell` inside a shell is not
  supported.

## See also

* [Interactive Shell](../tutorial/shell) – full tutorial on using the interactive shell
* [run - Execute a command in the sandbox](./run) – the `run` command used by implicit bare commands
* [file - Stage file edits for the next run](./file) – the `file edit` command behind editor aliases


# show - Inspect an operation
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/show



<Note>
  **`contree show` is a top-level shortcut for [operation show](./operation) (`contree op show`).**

  Both share one argparse setup and one handler. The top-level `show`
  accepts one or more UUIDs and history references — each entry renders
  as its own row. Accepted reference forms:

  * `@`, `:`, or `HEAD` — the operation at the active branch tip.
  * `@N`, `:N`, bare `N` — absolute history id.
  * `@-N`, `:-N`, `HEAD~N` — N steps back from the tip.
  * `HEAD~` — shorthand for `HEAD~1`.
  * `@+N`, `:+N` — N steps forward from the tip (latest child).

  See the [operation - Manage operations](./operation) page for the full description.
</Note>

Display the full result of one or more operations, including stdout
and stderr from sandbox execution.

## Examples

```bash theme={null}
# Show a single operation
contree show 3f2a7b...

# Show multiple operations in one call
contree show 3f2a7b... a1b2c3... 9d8e7f...

# History references (resolved against the active session)
contree show @5 @4 @3
# Relative to the active branch tip (like `session rollback`)
contree show @-1          # the operation one step back from the tip
contree show @+1          # the next operation forward (latest child)
# Git-style HEAD notation, equivalent to @ and @-N
contree show HEAD         # current tip operation
contree show HEAD~        # one step back (shorthand for HEAD~1)
contree show HEAD~3       # three steps back from the tip

# JSON output for scripting
contree -o json show 3f2a7b...

# Show result of a detached run
contree run -d -- make test
contree show UUID
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree show --help</div></div><pre><code><span>usage: </span><span>contree show</span><span> \[</span><span>-h</span><span>] \[</span><span>--raw</span><span>] </span><span>UUID\_OR\_REF \[UUID\_OR\_REF ...]</span><br /><br /><span>Manage operations (list, inspect, cancel).</span><br /><br /><span>Aggregates ps/show/kill under a single namespace, and adds multi-UUID</span><br /><span>support to \`\`show\`\` and \`\`cancel\`\` so several operations can be acted</span><br /><span>on in one invocation.</span><br /><br /><span>Subcommands:</span><br /><span>  list (ls)             List operations. \`\`contree ps\`\` is an alias.</span><br /><span>  show UUID \[UUID...]   Show one or more operation results.</span><br /><span>  cancel UUID \[UUID...] Cancel one or more operations (or --all).</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>UUID\_OR\_REF</span><span>  Operations to inspect. Accepts UUIDs and session-history references: @ or HEAD for</span><br /><span>               the active branch tip, @N for an absolute history id, @-N or HEAD\~N for N steps</span><br /><span>               back, @+N for N steps forward.</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>   show this help message and exit</span><br /><span>  </span><span>--raw</span><span>        Print each operation's JSON payload as JSONL (one object per line) to stdout.</span><br /><span>               Round-trips through the typed operation model, so fields the model doesn't know</span><br /><span>               about are dropped. Skips formatter routing and derived columns; streams cleanly</span><br /><span>               into \`jq -c\`. Useful for debugging or for fields the table view omits.</span><br /><br /><span>for coding agents:</span><br /><span>  list/show are read-only; cancel mutates remote state</span><br /><span>  show and cancel accept multiple UUIDs in one invocation</span><br /><span>  show supports @N session-history references inherited from \`contree show\`</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Output

The command renders every scalar top-level field the API returns
(typically: **uuid**, **kind**, **status**, **created\_at**,
**started\_at**, **finished\_at**, **duration**, **session\_key**, …) and
adds these derived fields:

* **exit\_code** – the sandbox process exit code (extracted from
  `metadata.result.state.exit_code`)
* **image** – resulting image UUID from `result.image`
* **tag** – image tag from `result.tag`
* **stdout / stderr** – sandbox output, decoded (for `default`,
  `json`, and `json-pretty` formats)

`status` is the server’s word: it reflects whether the API ran the
operation to completion, not whether the sandbox process exited with
zero. A `SUCCESS` row with `exit_code=1` means “the API completed the
job; your command returned 1”. `error` is pinned to the last column.
Nested objects (`metadata`, `result`) are dropped from the flat row
– use `--raw` to keep them, or `-o json` to keep the flat structured
row.

Pass `--raw` to skip all of the above and print each operation’s
JSON payload as JSONL (one object per line) to stdout. The payload
round-trips through the typed operation model, so fields the model
doesn’t know about are dropped – it’s not the server’s byte-for-byte
response. Streams cleanly into `jq -c`. Useful for debugging or
pulling fields the table view omits (resources, full metadata, etc.).

Timestamps come back from the API in UTC and are converted to the
**local timezone** for human-readable formatters (`default`, `table`,
`csv`, `tsv`, `plain`). The JSON formatters preserve the source
timezone offset.

For `csv`, `tsv`, and `table` formats, stdout/stderr are omitted – use
`default` or `json` to see sandbox output.

## See also

* [ps - List activity](./ps) – list operations to find UUIDs
* [operation - Manage operations](./operation) – multi-UUID variant: `contree op show UUID1 UUID2 ...`
* [run - Execute a command in the sandbox](./run) – the command that creates operations


# skill - Install agent skills
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/skill



Install, remove, or upgrade ConTree agent skills for Codex and Claude Code.

## Spec format

Commands accept **specs** – a `kind:hint` URI that identifies the skill type
and target path:

| Spec                | Resolves to                                                              | Skill type          |
| ------------------- | ------------------------------------------------------------------------ | ------------------- |
| `claude:`           | `.claude/skills/contree` (project)                                       | ClaudeSkill         |
| `claude:~`          | `~/.claude/skills/contree` (global)                                      | ClaudeSkill         |
| `codex:`            | `.codex/skills/contree` (project)                                        | CodexSkill          |
| `codex:~`           | `~/.codex/skills/contree` (global)                                       | CodexSkill          |
| `opencode:`         | `.opencode/skills/contree` (project)                                     | OpenCodeSkill       |
| `opencode:~`        | `$OPENCODE_HOME/skills/contree` (or `~/.config/opencode/skills/contree`) | OpenCodeSkill       |
| `amp:`              | `.amp/skills/contree` (project)                                          | AmpSkill            |
| `amp:~`             | `~/.config/agents/skills/contree` (global)                               | AmpSkill            |
| `cline:`            | `.cline/skills/contree` (project)                                        | ClineSkill          |
| `cline:~`           | `$CLINE_DIR/skills/contree` (or `~/.cline/skills/contree`)               | ClineSkill          |
| `claude-subagent:`  | `.claude/agents/contree-subagent.md` (project)                           | ClaudeSubagentSkill |
| `claude-subagent:~` | `~/.claude/agents/contree-subagent.md` (global)                          | ClaudeSubagentSkill |
| `claude-agent:`     | `.claude/agents/contree.md` (project)                                    | ClaudeAgentSkill    |
| `claude-agent:~`    | `~/.claude/agents/contree.md` (global)                                   | ClaudeAgentSkill    |
| `./path`            | `./path` (skill type guessed from path)                                  | auto                |

When no specs are given, `install` targets the global (`:~`) variant of
**every** known kind. The Claude-based kinds (`claude`, `claude-agent`,
`claude-subagent`) are skipped unless `~/.claude` already exists, so a
machine without Claude Code installed will not have empty directories
created for it.

## Examples

```bash theme={null}
# Install globally to every known kind (Claude kinds gated on ~/.claude)
contree skill install

# Install into project-level .claude/skills/contree
contree skill install claude:

# Install globally into ~/.claude/skills/contree
contree skill install claude:~

# Install both globally
contree skill install codex:~ claude:~

# Install to explicit path (class guessed from path)
contree skill install ./my/custom/path

# Upgrade all remembered installs
contree skill upgrade

# Upgrade specific target
contree skill upgrade claude:~

# Remove by spec
contree skill remove -y claude:~

# Remove by full path
contree skill remove -y /path/to/skills/contree

# List installs with version and outdated status
contree skill list
contree skill ls
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree skill --help</div></div><pre><code><span>usage: </span><span>contree skill</span><span> \[</span><span>-h</span><span>] </span><span>\{list,ls,install,i,remove,r,rm,del,upgrade,u,update} ...</span><br /><br /><span>Install, remove, or upgrade ConTree agent skills.</span><br /><br /><span>contree skill install              # autodetect agent homes</span><br /><span>contree skill install claude:\~     # global \~/.claude</span><br /><span>contree skill install codex:       # project-level .agents/skills</span><br /><span>contree skill install .            # project root: every kind under it</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>\{list,ls,install,i,remove,r,rm,del,upgrade,u,update}</span><br /><span>    </span><span>list (ls)</span><span>           List remembered skill installs</span><br /><span>    </span><span>install (i)</span><span>         Install ConTree skill files</span><br /><span>    </span><span>remove (r, rm, del)</span><br /><span>                        Remove installed skill files</span><br /><span>    </span><span>upgrade (u, update)</span><br /><span>                        Upgrade installed skill files</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>            show this help message and exit</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Subcommands

### `skill install`

`contree skill install [SPEC ...]` (alias `i`) installs skill directories.
Each spec resolves to a skill class and a filesystem path, both of which
are persisted in `skills.db` so future `list` and `upgrade` calls can
find the install without re-specifying it. With no specs the command
targets the global (`:~`) variant of every known kind – Claude-based
kinds are skipped automatically when `~/.claude` does not exist. Pass
`-y` to overwrite an existing install non-interactively.

<div><div><div><span /><span /><span /></div><div>\$ contree skill install --help</div></div><pre><code><span>usage: </span><span>contree skill install</span><span> \[</span><span>-h</span><span>] \[</span><span>-f</span><span>] </span><span>\[SPEC ...]</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>SPEC</span><span>             claude:\~ codex:\~ skill path or project root</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><span>  </span><span>-f</span><span>, </span><span>-y</span><span>, </span><span>--force</span><span>  Overwrite existing</span></code></pre></div>

### `skill list`

`contree skill list` (alias `ls`) shows every remembered install with
its kind, installed version (read from `.version`), the version
bundled with this CLI, an `outdated` flag, and whether the install
path still exists on disk. Stale entries whose path was deleted
externally are pruned from the registry automatically when this
command runs.

<div><div><div><span /><span /><span /></div><div>\$ contree skill list --help</div></div><pre><code><span>usage: </span><span>contree skill list</span><span> \[</span><span>-h</span><span>]</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span></code></pre></div>

### `skill upgrade`

`contree skill upgrade [SPEC ...]` overwrites existing installs with
the version bundled in the current CLI. With no specs it upgrades
every remembered location, which is the normal post-`pip install -U`
maintenance step. Targets that are already at the bundled version are
rewritten anyway so any local edits to skill files are reverted.

<div><div><div><span /><span /><span /></div><div>\$ contree skill upgrade --help</div></div><pre><code><span>usage: </span><span>contree skill upgrade</span><span> \[</span><span>-h</span><span>] </span><span>\[SPEC ...]</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>SPEC</span><span>        claude:\~ codex:\~ skill path or project root</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span></code></pre></div>

### `skill remove`

`contree skill remove SPEC [...]` (aliases `r`, `rm`, `del`) deletes
installed skill files and forgets the path from the registry. Specs
may be the same URI form accepted by `install`, or a literal filesystem
path. Pass `-y` to skip the confirmation prompt.

<div><div><div><span /><span /><span /></div><div>\$ contree skill remove --help</div></div><pre><code><span>usage: </span><span>contree skill remove</span><span> \[</span><span>-h</span><span>] \[</span><span>-f</span><span>] </span><span>\[SPEC ...]</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>SPEC</span><span>             claude:\~ codex:\~ skill path or project root</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>       show this help message and exit</span><br /><span>  </span><span>-f</span><span>, </span><span>-y</span><span>, </span><span>--force</span><span>  Do not ask for confirmation</span></code></pre></div>

### Install contents

Skill directories contain:

* `.version` — installed package version
* `SKILL.md` — skill prompt with `allowed-tools` frontmatter
* `agents/openai.yaml` — OpenAI-compatible skill config

Skills require `contree` in PATH. If missing, ask the user to install it.

### Skill classes

| Class                 | Kind              | Description                                 |
| --------------------- | ----------------- | ------------------------------------------- |
| `ClaudeSkill`         | `claude`          | Bundled skill directory for Claude Code     |
| `CodexSkill`          | `codex`           | Bundled skill directory for Codex           |
| `OpenCodeSkill`       | `opencode`        | Bundled skill directory for OpenCode        |
| `AmpSkill`            | `amp`             | Bundled skill directory for Amp             |
| `ClineSkill`          | `cline`           | Bundled skill directory for Cline           |
| `ClaudeSubagentSkill` | `claude-subagent` | Standalone `.md` subagent file              |
| `ClaudeAgentSkill`    | `claude-agent`    | Custom agent `.md` with `skills: [contree]` |


# tag - Tag or untag an image
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/tag



Assign or remove a tag from an image. Tags are human-readable names that
make images easier to reference.

## Examples

```bash theme={null}
# Tag an image
contree tag 3f2a7b... my-app:v1.0

# Remove a tag
contree tag 3f2a7b... my-app:v1.0 --delete

# Use the tagged image
eval $(contree use tag:my-app:v1.0)
```

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree tag --help</div></div><pre><code><span>usage: </span><span>contree tag</span><span> \[</span><span>-h</span><span>] \[</span><span>-U</span><span>] </span><span>ARG \[ARG ...]</span><br /><br /><span>Assign or remove a tag from an image.</span><br /><br /><span>Tags provide human-readable names for image UUIDs, making them easier</span><br /><span>to reference in commands like \`contree use tag:NAME\`.</span><br /><br /><span>With one argument, tags the current session image.</span><br /><span>With two arguments, the first is the image reference and the second is the tag.</span><br /><br /><span>Use -U/--delete/--rm to remove a tag instead of assigning one.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>ARG</span><span>                 TAG (current image) or IMAGE\_REF TAG</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>          show this help message and exit</span><br /><span>  </span><span>-U</span><span>, </span><span>--delete</span><span>, </span><span>--rm</span><span>  Remove tag from image</span><br /><br /><span>examples:</span><br /><span>  contree tag python-dev:latest            # tag current session image</span><br /><span>  contree tag UUID python-dev:latest       # tag specific image by UUID</span><br /><span>  contree tag tag:alpine:latest my-alpine  # re-tag by reference</span><br /><span>  contree tag -U UUID my-tag               # remove a tag (or --delete/--rm)</span><br /><br /><span>for coding agents:</span><br /><span>  mutating command</span><br /><span>  default action assigns tag; use --delete to remove mapping</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Usage

Tags are free-form strings. A common convention is `scope/purpose:version`:

```bash theme={null}
contree tag UUID ubuntu-with-curl:latest
contree tag UUID my-project/dev-env:v2
```

Once tagged, reference the image anywhere with the `tag:` prefix:

```bash theme={null}
contree use tag:ubuntu-with-curl:latest
```

Tagging an image that already has a different tag replaces the old tag.

## See also

* [images - List and import images](./images) – list images and their tags
* [Your First Sandbox](../tutorial/first-steps) – working with images


# use - Choose an image for the session
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/use



Set the session image or show the current session state.

This is typically the first command you run – it tells contree-cli which
image to use for subsequent commands.

## Examples

```bash theme={null}
# Start a session with an image
eval $(contree use tag:ubuntu:latest)

# Start a session with a specific image UUID
eval $(contree use 3f2a7b...)

# Start or resume a named session
export CONTREE_SESSION=my-session

# Show current session info
contree use

# Start a fresh session (new session key)
eval $(contree use -N tag:python:3.11-slim)
```

The `eval` wrapper exports `CONTREE_SESSION` into your shell so all
subsequent commands share the same session. Without `eval`, contree prints
the export line but your shell doesn’t pick it up.

## Help output

<div><div><div><span /><span /><span /></div><div>\$ contree use --help</div></div><pre><code><span>usage: </span><span>contree use</span><span> \[</span><span>-h</span><span>] \[</span><span>-N</span><span>] </span><span>\[image]</span><br /><br /><span>Set or show the current session image.</span><br /><br /><span>With an IMAGE argument, resolves it (UUID or tag:NAME) and sets it as</span><br /><span>the active session image. Prints a shell export line so that the</span><br /><span>session key can be captured with eval:</span><br /><br /><span>  eval \$(contree use tag:ubuntu:latest)</span><br /><br /><span>Without arguments, displays the current session info (image, branch,</span><br /><span>last operation).</span><br /><br /><span>Use -N/--new to start a fresh session instead of resuming the current</span><br /><span>one. The new session key is printed as an export line.</span><br /><br /><span>positional arguments:</span><br /><span>  </span><span>image</span><span>       Image UUID or tag</span><br /><br /><span>options:</span><br /><span>  </span><span>-h</span><span>, </span><span>--help</span><span>  show this help message and exit</span><br /><span>  </span><span>-N</span><span>, </span><span>--new</span><span>   Start a new session instead of resuming the current one</span><br /><br /><span>for coding agents:</span><br /><span>  use IMAGE starts/switches a session and prints CONTREE\_SESSION export</span><br /><span>  use (without IMAGE) is read-only and prints current session state</span><br /><span>  use --new IMAGE creates a fresh session key</span><br /><span>  without CONTREE\_SESSION env var, key is auto-generated as \<cwd>+\<8hex></span><br /><span>  (derived from profile+ppid+tty); export your own for stability</span><br /><br /><span>agent note:</span><br /><span>  Before using this command in an automated workflow, read:</span><br /><span>    contree agent</span></code></pre></div>

## Behavior

**With an image argument**: resolves the image (UUID or `tag:NAME`), sets it
as the session’s current image, and prints a shell export statement.

**Without arguments**: displays the current session info – session key,
active branch, current image, and last operation.

**With `--new`**: generates a new random session key instead of resuming the
existing one. Useful when you want a clean slate in the same terminal.

## Shell detection

The output format adapts to your shell:

* **bash / zsh**: `export CONTREE_SESSION=<key>`
* **fish**: `set -gx CONTREE_SESSION <key>`

Detection uses the `$SHELL` environment variable.

## See also

* [Your First Sandbox](../tutorial/first-steps) – starting your first session
* [Sessions, Branches & Rollback](../tutorial/sessions) – branching and rollback


# Overview
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/index



Command-line client for the [ConTree](https://contree.dev) sandboxing platform.

## What is ConTree?

[ConTree](https://contree.dev) is a secure sandbox API for AI agents with
git-like branching. Every command runs inside a VM-isolated sandbox, and
every execution produces a new **image** – a full filesystem snapshot.
Branch from any checkpoint, explore paths in parallel, pick the winner,
and instantly roll back on failure.

Built for **AI agents that think ahead**:

* **Tree-search execution** – branch the sandbox state so an agent can
  explore multiple solution paths in parallel and keep the best one.
* **Instant rollback** – backtrack to any previous checkpoint when a
  path fails, without rebuilding from scratch.
* **Safe code execution** – run untrusted or LLM-generated code inside
  VM-level isolation. Crashes and side effects stay in the sandbox.
* **Session continuity** – rewind and resume long-running agent
  workflows with full filesystem context preserved.

`contree-cli` is the command-line client that talks to the ConTree API.

```bash theme={null}
contree use tag:ubuntu:latest      # pick an image for current terminal
contree run apt update -qq         # each run snapshots the result
contree run apt install -y curl    # builds on the previous snapshot
contree ls /usr/bin/curl           # inspect without spawning a VM
```

You can choose name for session by setting the environment variable
`CONTREE_SESSION`.

```bash theme={null}
export CONTREE_SESSION=demo_session  # Pick a name for session manually
contree use tag:ubuntu:latest        # pick an image for demo_session
contree run -- find /root            # run commands
```

## Get started

<Columns>
  <Card title="Tutorial" href="./tutorial/index" icon="graduation-cap">
    Step-by-step guide from installation to automated workflows.
    Six sections, each building on the previous one.
  </Card>

  <Card title="Command Reference" href="./commands/index" icon="book-open-cover">
    Every command, flag, and subcommand documented with usage examples.
  </Card>
</Columns>

## Key features

<Columns>
  <Card title="Sessions & Branching" href="./tutorial/sessions" icon="code-branch">
    Every run creates a checkpoint. Branch off to experiment, roll back
    mistakes, resume from any point.
  </Card>

  <Card title="File Injection" href="./tutorial/files" icon="folder-open">
    Map local files into sandboxes with `--file`, edit remote configs
    in-place, stage changes for the next run.
  </Card>

  <Card title="Scripting-Friendly" href="./tutorial/workflows" icon="gears">
    JSON, CSV, and TSV output. Detached runs, operation monitoring,
    shebang scripts — built for automation.
  </Card>

  <Card title="Lightweight">
    A single runtime dependency: the `contree-client` library.
  </Card>

  <Card title="Multi-Profile" href="./tutorial/configuration" icon="gear">
    Named profiles for different projects and environments. Switch with
    a single command.
  </Card>

  <Card title="Filesystem Inspection" href="./commands/ls" icon="list-ul">
    Browse and download files from sandbox images without spawning a
    new instance.
  </Card>
</Columns>


# Building from a Dockerfile
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/build



`contree build` turns a familiar `Dockerfile` into a ConTree image. Each
directive becomes one image layer, every layer is a real session
checkpoint, and re-running the same `Dockerfile` reuses prior layers
through a content-addressed cache. This tutorial walks through the
`build-demo` example shipped with the repo so you can see the moving
parts end-to-end.

## The example project

The tree at `docs/examples/build-demo` contains a minimal Python app
plus a Dockerfile that exercises the directives most builds actually
use:

```
docs/examples/build-demo/
├── .dockerignore
├── Dockerfile
├── hello.py
└── src/
    ├── __init__.py
    └── banner.py
```

`hello.py` reads a greeting from an environment variable and prints a
boxed banner; `src/banner.py` provides the box renderer. Nothing
exotic – it just gives the Dockerfile something to `COPY` and `RUN`.

The Dockerfile itself:

```dockerfile theme={null}
FROM python:3.12-alpine

ARG GREETING=hello
ENV APP_GREETING=${GREETING}

WORKDIR /app

COPY hello.py /app/hello.py
COPY src /app/src
ADD https://github.com/nebius/contree-cli/archive/refs/heads/master.zip /tmp/contree-cli.zip

RUN python -c "import sys; print('python', sys.version)"
RUN python -m zipfile -e /tmp/contree-cli.zip /opt/
RUN pip install --no-cache-dir /opt/contree-cli-master
RUN contree --help | head -20
RUN python /app/hello.py
```

Six directives, in order:

1. `FROM python:3.12-alpine` – resolves the base image. If
   `tag:python:3.12-alpine` is not already in the project, `contree build`
   auto-imports it from the registry.
2. `ARG GREETING=hello` and `ENV APP_GREETING=${GREETING}` – declare a
   build-time variable and pin its value into a runtime environment
   variable that the app will read.
3. `WORKDIR /app` – sets the working directory for everything below.
4. Two `COPY` directives stage local files (`hello.py` and the `src/`
   directory) into the build’s pending uploads.
5. `ADD https://...master.zip /tmp/contree-cli.zip` – streams a remote
   archive straight from GitHub into the contree file store, without
   creating a local temp file.
6. Five `RUN` directives prove the toolchain works, unpack the zip,
   install the CLI from source, and run the demo app.

## Build context and `.dockerignore`

The first positional argument to `contree build` is the **build
context** – the directory that anchors every `COPY` and `ADD` source
path. Anything outside that directory is invisible to the build. In
this example the context is `docs/examples/build-demo`, and the
Dockerfile sits at the top of it.

A `.dockerignore` next to the Dockerfile keeps junk out of the upload:

```text theme={null}
# Demo .dockerignore: keep build context lean
**/*.log
**/__pycache__
.env*
```

The matcher uses the same rule set as `run --file`: `*` is a
single-segment wildcard, `**` crosses directories, `?` matches one
character, and a leading `!` re-includes a previously ignored path.
The last matching rule wins. On top of your `.dockerignore`, the CLI
always filters `.git`, `__pycache__`, `*.pyc`, `.venv`,
`node_modules`, `dist`, and `build`, so you do not need to repeat the
usual suspects.

## Your first build

From the repository root, run:

```bash theme={null}
contree build docs/examples/build-demo --tag contree-cli-build-demo:latest
```

You should see one log line per directive plus a stdout dump after
each `RUN`:

```text theme={null}
[INFO] FROM python:3.12-alpine -> tag:python:3.12-alpine
[INFO] COPY hello.py -> /app/hello.py
[INFO] COPY src -> /app/src
[INFO] ADD https://.../master.zip -> /tmp/contree-cli.zip
[INFO] RUN spawned op=019e... RUN python -c "import sys; print('python', sys.version)"
[INFO] stdout:
python 3.12.13 ...
[INFO] RUN spawned op=019e... RUN python /app/hello.py
[INFO] stdout:
+---------------+
|     hello     |
| contree build |
+---------------+
[INFO] tagged <uuid> as contree-cli-build-demo:latest
IMAGE                                 TAG                            SESSION
<uuid>                                contree-cli-build-demo:latest  build:<sha16>
```

The final tagged image is now usable everywhere a tag is accepted:

```bash theme={null}
eval $(contree use tag:contree-cli-build-demo:latest)
contree run python /app/hello.py
```

## Layer cache: the second build is free

Run the same command a second time. Every step prints **cache hit**
and the build finishes in seconds without spawning a single instance.

The cache key for each layer is a chain hash:

```
sha256(parent_layer_hash || state(workdir/env/user/args)
       || directive || pending_files)
```

That means a layer is reused if and only if:

* the previous layer was identical,
* the directive text is byte-for-byte the same,
* the resolved environment (`WORKDIR`, `ENV`, `USER`, `ARG`) matches, and
* for `COPY`/`ADD`, the **content** of the staged files matches (the
  SHA-256 of every uploaded file, not their timestamps).

Edit `hello.py`, run the build again, and only the last `RUN` step
plus everything depending on it rebuilds. The earlier `RUN python -c 'import sys; print(sys.version)'` layer is reused because it has no
dependency on `hello.py`.

Each cached layer is materialised as a branch named
`layer:<chain-hash>` inside a session keyed by the absolute path of
the context directory: `build:<sha16(abspath(context))>`. So the
cache is **per-context-path** – moving the directory or building from
a sibling worktree starts a fresh cache.

To inspect the layer history:

```bash theme={null}
contree session list --filter build:
contree session use build:<sha16>
contree session show
```

`contree session show` prints the DAG with one row per layer and the
chain hash visible in the branch column. Switching to a `layer:` branch
puts you on that layer’s image, so you can `contree run` against any
intermediate snapshot to debug a step in isolation.

To force a rebuild ignoring all cached layers:

```bash theme={null}
contree build docs/examples/build-demo --no-cache \
  --tag contree-cli-build-demo:latest
```

## Build args and variable substitution

Variables (`$VAR` and `${VAR}`) expand in `FROM`, `RUN`, `COPY`/`ADD`
arguments, `WORKDIR`, `ENV` values, and `USER`. The lookup order is:

1. `--build-arg KEY=VALUE` for any `ARG` already declared.
2. `ENV` directives processed so far.
3. `ARG` defaults from the Dockerfile.
4. Empty string for unknown names.

The demo declares `ARG GREETING=hello` and uses it through
`ENV APP_GREETING=${GREETING}`. Override it at the CLI:

```bash theme={null}
contree build docs/examples/build-demo --build-arg GREETING=ciao \
  --tag contree-cli-build-demo:ciao
```

The final `RUN python /app/hello.py` step now prints `ciao` in the
boxed banner because the chain hash of the layer that ran
`ENV APP_GREETING=...` changed, invalidating every layer below it.

## `ADD URL` streams without a temp file

The `ADD` line in the demo points at a GitHub archive:

```dockerfile theme={null}
ADD https://github.com/nebius/contree-cli/archive/refs/heads/master.zip /tmp/contree-cli.zip
```

`contree build` opens the HTTP connection and pipes the response body
**directly** into `POST /v1/files` – the bytes never touch your local
disk. The CLI also remembers the URL’s `ETag`, `Last-Modified`, and
`Content-MD5` validators in the per-context cache. On the next build
it issues a conditional `HEAD` first; if the validators match, the
upload is skipped entirely and the log line reads
`URL cache hit (HEAD validators match)`.

Two things this does **not** do:

* It does not extract tarballs/zips. Use a `RUN python -m zipfile -e`
  (or `tar xf`) directive when you need extraction, exactly like the
  demo does.
* It does not follow private auth – the request is anonymous. Mirror
  the asset to a public URL, or `COPY` it from your build context.

## Supported and skipped directives

The MVP interpreter implements the directives most Dockerfiles
actually rely on:

| Implemented                              | Notes                                                                               |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `FROM ref[:tag] [AS name]`               | Auto-imports missing tags; `AS name` is parsed but multi-stage is not yet executed. |
| `RUN ...`                                | Shell-form and JSON exec-form. Spawns one instance per `RUN`.                       |
| `COPY [--chown=] [--chmod=] SRC... DEST` | Honours `.dockerignore`, dedups by SHA-256.                                         |
| `ADD ...`                                | Local paths behave like `COPY`; URLs stream through `POST /v1/files`.               |
| `WORKDIR`, `ENV`, `ARG`, `USER`          | Accumulated and applied to subsequent steps.                                        |

Directives that are parsed and **skipped with a warning** (the build
continues, the image is still produced):

`CMD`, `ENTRYPOINT`, `LABEL`, `EXPOSE`, `VOLUME`, `STOPSIGNAL`,
`MAINTAINER`, `HEALTHCHECK`, `ONBUILD`, `SHELL`,
`COPY --from=stage`.

ConTree images are filesystem snapshots, not OCI runtime configs, so
`CMD`/`ENTRYPOINT` have nowhere to live – you express the entrypoint
explicitly at `contree run` time instead.

## When to reach for `build` vs `run`

The same image you can produce with `contree build` can be produced
by hand with a sequence of `contree run` calls. Pick the right tool:

| Situation                                                          | Prefer                                                                  |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| You already have a working `Dockerfile`                            | `contree build` – just reuse it.                                        |
| You want reproducible, cacheable setup driven from version control | `contree build`.                                                        |
| You are still experimenting and do not know the final steps        | `contree run` interactively; tag a checkpoint when you are happy.       |
| You need `CMD`/`ENTRYPOINT`/`HEALTHCHECK` semantics                | Neither – those are runtime concerns for OCI runtimes, not for ConTree. |
| You want multi-stage builds today                                  | Not yet – stage `AS` parses but is skipped. Track Phase 2.              |

## Cheat sheet

```bash theme={null}
# Simplest build; finds ./Dockerfile in the context, tags the result.
contree build . --tag myapp:dev

# Out-of-tree Dockerfile.
contree build ./service \
  --dockerfile ./service/Dockerfile.prod \
  --tag svc:prod

# Override build-time variables.
contree build . \
  --build-arg VERSION=2.5 \
  --build-arg DEBUG=1

# Force a full rebuild.
contree build . --no-cache --tag myapp:dev

# Raise the per-RUN timeout to 30 minutes.
contree build . --timeout 1800 --tag myapp:dev

# Inspect the build's layer history.
contree session list --filter build:
contree session use build:<sha16>
contree session show
```

***

You now have a tagged image that came from a `Dockerfile`, a cached
layer history you can branch off, and a feel for which directives
behave and which are parsed-but-skipped. Next, see
[Scripting & Automation](./workflows) for scripting builds into pipelines, or
[build - Build an image from a Dockerfile](../commands/build) for the full reference.


# Configuration & Profiles
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/configuration



Profiles let you store credentials for multiple projects or environments
and switch between them. This section walks through setting up profiles,
switching contexts, and understanding how configuration is resolved.

## Creating profiles

Each profile stores a token and API URL for a specific project or
environment. When you first ran `contree auth`, it created a profile
called `default`. Add more with `--profile`:

```bash theme={null}
contree auth --profile=personal
contree auth --profile=sandbox
```

Each command prompts for a token securely (no echo), verifies it against
the API, and writes it to `~/.config/contree/auth.ini`.

The resulting config file looks like this:

```ini theme={null}
[DEFAULT]
profile = default

[profile:default]
token = eyJ...
url = https://api.tokenfactory.nebius.com/sandboxes
type = iam
project = project-id-default

[profile:personal]
token = eyJ...
url = https://api.tokenfactory.nebius.com/sandboxes
type = iam
project = project-id-personal

[profile:sandbox]
token = eyJ...
url = https://api.tokenfactory.nebius.com/sandboxes
type = iam
project = project-id-sandbox
```

Each profile is a `[profile:NAME]` section with `token`, `url`, `type`,
and `project` keys. The `[DEFAULT]` section stores the name of the active
profile.

## Listing profiles

See all saved profiles and which one is active:

```bash theme={null}
contree auth ls
```

The output shows the profile name, URL, a token hash (first 16 chars of
SHA256), active status, and a health check result.

`auth ls` verifies each profile against the API with a 2-second timeout.
Possible status values:

* `ok` — token is valid and has the required sandbox permission
* `timeout` — server did not respond in time
* `error` — bad token or network error
* `offline mode` — you passed `-O` / `--offline`
* `no url` — the profile has no API URL configured (re-run `contree auth`)
* `inactive` — token authenticates, but the configured project does not
  grant the sandbox permission this CLI needs

Skip the network check:

```bash theme={null}
contree auth ls -O
```

For automation, use structured output:

```bash theme={null}
contree -o json auth ls
```

## Switching profiles

### Persistent switch

Change the active profile for all future commands:

```bash theme={null}
contree auth switch personal
```

### Per-command override

Use `-p` / `--profile` on any command:

```bash theme={null}
contree -p personal images
contree -p sandbox run -- uname -a
```

### Environment variable

Override for the entire shell session:

```bash theme={null}
export CONTREE_PROFILE=sandbox
contree images        # uses sandbox
```

### Inline token

Pass `--token` and `--url` directly:

```bash theme={null}
contree --token=eyJ... --url=https://api.tokenfactory.nebius.com/sandboxes images
```

<Warning>
  Avoid `--token` on the command line in production — the token is
  visible in process listings and shell history.
</Warning>

## Removing profiles

Delete a profile and its session database:

```bash theme={null}
contree auth remove personal
contree auth rm personal -y    # skip confirmation
```

If the removed profile was active, the CLI switches to the first
remaining profile.

## Profiles and sessions

Each profile has its own session database
(`~/.config/contree/sessions-{profile}.db`), so:

* **Same profile, same terminal** — resumes the existing session
* **Different profile, same terminal** — different session, different data

Switching from `default` to `personal` does not affect your `default`
sessions — you can switch back and continue where you left off.

<Tip>
  To share a session across profiles (rare), set `CONTREE_SESSION`:

  ```bash theme={null}
  export CONTREE_SESSION=shared-session
  ```
</Tip>

## Data storage

All data lives in `CONTREE_HOME` (default `$XDG_CONFIG_HOME/contree`,
falling back to `~/.config/contree` when `XDG_CONFIG_HOME` is unset):

| Path                        | Purpose                                                     |
| --------------------------- | ----------------------------------------------------------- |
| `auth.ini`                  | Profile credentials and settings (created with mode `0600`) |
| `cli.ini`                   | Optional user-editable defaults for the CLI                 |
| `cli/sessions/{profile}.db` | Per-profile sessions, history, branches, cache              |
| `cli/skills.db`             | Installed agent skill registry                              |

Override with `$CONTREE_HOME`:

```bash theme={null}
export CONTREE_HOME=/custom/path
```

### `cli.ini`

`cli.ini` is meant for hand-editing. Create it yourself; the CLI never
writes to it. Two kinds of sections are supported:

#### `[cli]` section: per-flag defaults

Keys here become argparse defaults. Use the argparse `dest` name (not
the flag name):

| Key             | Maps to flag           | Notes                                                                                                                                |
| --------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `log_level`     | `--log-level`          | One of `debug`, `info`, `warning`, `error`, `critical`                                                                               |
| `output_format` | `-f` / `--format`      | One of the formatter names (`default`, `json`, `json-pretty`, `csv`, `tsv`, `table`)                                                 |
| `editor`        | `--editor` (file edit) | Fallback when neither `--editor` nor `$EDITOR` is set; if absent the CLI searches `vim` then `nano` on `PATH` and falls back to `vi` |

Example:

```ini theme={null}
[cli]
log_level = debug
output_format = json
editor = nvim
```

Precedence: CLI flag > environment variable > `cli.ini` > built-in
default. A `cli.ini` setting always loses to an explicit flag.

#### `[profile:NAME]` sections: CLI-scoped profiles

`cli.ini` accepts the same `[profile:NAME]` sections as `auth.ini` and
supports the same fields:

| Key       | Required                      | Notes                    |
| --------- | ----------------------------- | ------------------------ |
| `url`     | yes for JWT, optional for IAM | API base URL             |
| `type`    | optional                      | `jwt` (default) or `iam` |
| `project` | IAM only                      | Project ID               |
| `token`   | optional                      | API bearer token         |

The two files are merged at load time and `auth.ini` wins on conflict.

What `cli.ini` is for: profiles (or any field, including `token`) you
want only the `contree` CLI to see. The CLI merges `cli.ini` with
`auth.ini`. Other contree-related tooling that talks to the API
directly (the SDK, the MCP server) reads only `auth.ini`. Use
`cli.ini` when you need a profile that should be invisible to those
direct-API consumers, or to keep `auth.ini` minimal and shared.

Example, CLI-only profile alongside the shared one:

```ini theme={null}
# ~/.config/contree/auth.ini  (read by CLI + SDK + MCP, mode 0600)
[DEFAULT]
profile = default

[profile:default]
url = https://contree.dev
token = eyJhbGciOi...
```

```ini theme={null}
# ~/.config/contree/cli.ini  (read only by the CLI)
[profile:cli-sandbox]
url = https://staging.contree.dev
token = eyJhbGciOi...different
```

The active profile is still selected by the `profile` key in
`[DEFAULT]` of `auth.ini` (or by `--profile` / `$CONTREE_PROFILE`).

## Environment variables

Read at runtime by any command:

| Variable          | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `CONTREE_HOME`    | Data directory (default `$XDG_CONFIG_HOME/contree`, or `~/.config/contree`) |
| `XDG_CONFIG_HOME` | XDG base config dir, used to derive the default `CONTREE_HOME`              |
| `CONTREE_PROFILE` | Active profile name (selects which profile commands use)                    |
| `CONTREE_SESSION` | Explicit session key (overrides auto-generated)                             |

Read only by `contree auth` (registration-time fallbacks for omitted flags):

| Variable                                | Used for    |
| --------------------------------------- | ----------- |
| `CONTREE_TOKEN` / `NEBIUS_API_KEY`      | `--token`   |
| `CONTREE_URL`                           | `--url`     |
| `CONTREE_PROJECT` / `NEBIUS_AI_PROJECT` | `--project` |

## Resolution precedence

For token, URL, and project at runtime:

1. CLI flag (`--token`, `--url`, `--project`) — overrides profile for the
   current invocation only
2. Saved profile field
3. Built-in default URL for IAM: `https://api.tokenfactory.nebius.com/sandboxes`

Environment variables are not consulted at runtime; to refresh credentials
from environment variables, run `contree auth` (which reads
`CONTREE_TOKEN` / `NEBIUS_API_KEY`, `CONTREE_URL`, and `CONTREE_PROJECT` /
`NEBIUS_AI_PROJECT` as fallbacks for the corresponding flags).

For profiles:

1. `-p` / `--profile` flag
2. `CONTREE_PROFILE` environment variable
3. `profile` key in config `[DEFAULT]` section
4. Falls back to `default`

***

See [auth - Configure credentials and profiles](../commands/auth) for the full auth command reference, or
[Command Reference](../commands/index) for all commands.


# Working with Files
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/files



contree-cli lets you inject local files into sandboxes, edit remote files
in-place, and stage changes that automatically apply on the next run.

## Inject a file with `--file`

Use `--file` / `-F` on `contree run` to attach a local file:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run --file ./app.py python /app.py
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree run --file ./app.py python /app.py
    ```

    Flags like `--file` require the explicit `contree run` prefix.
  </Tab>
</Tabs>

By default the file is placed at the same path inside the sandbox.
Specify a different destination with a colon:

<CodeGroup>
  ```bash CLI theme={null}
  contree run --file ./app.py:/app/main.py python /app/main.py
  ```

  ```text Shell theme={null}
  contree run --file ./app.py:/app/main.py python /app/main.py
  ```
</CodeGroup>

### Full `--file` syntax

```
host_path[:instance_path][:uUID][:gGID][:mMODE]
```

* **host\_path** – path to the file on your machine (required)
* **instance\_path** – destination path inside the sandbox (detected by
  leading `/`). Defaults to the host path.
* **uUID** – owner UID (prefix `u`). Numeric or name (resolved locally).
* **gGID** – group GID (prefix `g`). Numeric or name (resolved locally).
* **mMODE** – octal permission mode (prefix `m`).

Tagged options (`u`, `g`, `m`) can appear in any order after the host
path. Unspecified values default to the host file’s stat.

```bash theme={null}
# Override only mode
contree run --file ./script.sh:m0755 /script.sh

# All explicit
contree run --file ./app.py:/app.py:u0:g0:m0755 python /app.py

# Named uid/gid (resolved from local system)
contree run --file ./app.py:uroot:groot python /app.py
```

<Note>
  Named uid/gid (e.g. `uroot`) are resolved locally via `pwd`/`grp`
  modules. Use numeric IDs if unsure about host/instance mismatch.
</Note>

### Multiple files

Repeat the `--file` flag:

```bash theme={null}
contree run \
  --file ./app.py:/app.py \
  --file ./config.yaml:/etc/app/config.yaml \
  python /app.py
```

### Directories

`--file` also accepts directories. The entire tree is uploaded recursively:

```bash theme={null}
contree run --file ./src:/app/src -- make -C /app/src
```

Common junk is excluded by default: `.*`, `.git`, `*.pyc`, `__pycache__`,
`.venv`, `.mypy_cache`, `.pytest_cache`, `node_modules`, `dist`, `build`.

Add extra exclusions with `--file-excludes`:

```bash theme={null}
contree run --file ./project:/app --file-excludes '*.log' '*.tmp' -- make -C /app
```

### Upload caching

The CLI keeps a local upload cache keyed by file path, inode, modification
time, and size. Repeated attachments of unchanged files skip both the hash
calculation and the API call. The cache expires after 90 days to account
for server-side file retention.

The server also deduplicates by SHA256 — if the same content was uploaded
from a different session or machine, it is reused without re-uploading.

## Edit remote files

<Tabs>
  <Tab title="CLI">
    `contree file edit` downloads a file from the session image, opens it
    in your `$EDITOR`, and stages the changes as a pending file:

    ```bash theme={null}
    contree file edit /etc/nginx/nginx.conf
    ```
  </Tab>

  <Tab title="Shell">
    In the interactive shell, `vim`, `vi`, and `nano` are aliases for
    `contree file edit`, using your host `$EDITOR`:

    ```text theme={null}
    vim /etc/nginx/nginx.conf
    ```

    You can also use the full command:

    ```text theme={null}
    contree file edit /etc/nginx/nginx.conf
    ```
  </Tab>
</Tabs>

What happens step by step:

1. The file is downloaded from the current session image to a temp file
2. Your editor opens (`$EDITOR`, defaults to `vi`)
3. If you saved changes, the modified file is uploaded and staged as pending
4. If the file is unchanged (same SHA256), nothing is staged

If the file does not exist in the image yet, an empty file is created for
you to fill in.

### Iterate without re-running

You can edit multiple files before running:

<CodeGroup>
  ```bash CLI theme={null}
  contree file edit /etc/nginx/nginx.conf
  contree file edit /etc/nginx/sites-enabled/default
  contree run nginx -t                # test config with both edits applied
  ```

  ```text Shell theme={null}
  vim /etc/nginx/nginx.conf
  vim /etc/nginx/sites-enabled/default
  nginx -t
  ```
</CodeGroup>

Both edits are staged as pending and applied together on the next run.

## Stage local files with `contree file cp`

`contree file cp` copies a local file into the session as a pending file:

<CodeGroup>
  ```bash CLI theme={null}
  contree file cp ./config.yaml /etc/app/config.yaml
  ```

  ```text Shell theme={null}
  contree file cp ./config.yaml /etc/app/config.yaml
  ```
</CodeGroup>

This uploads the file and records it as pending – it does not run anything.
The file will be included in the next `contree run` automatically.

### Build up a working environment

<CodeGroup>
  ```bash CLI theme={null}
  contree file cp ./app.py /app/app.py
  contree file cp ./requirements.txt /app/requirements.txt
  contree file cp ./config.yaml /etc/app/config.yaml
  contree run pip install -r /app/requirements.txt
  contree run python /app/app.py
  ```

  ```text Shell theme={null}
  contree file cp ./app.py /app/app.py
  contree file cp ./requirements.txt /app/requirements.txt
  contree file cp ./config.yaml /etc/app/config.yaml
  pip install -r /app/requirements.txt
  python /app/app.py
  ```
</CodeGroup>

The first `run` consumes all three pending files and bakes them into the
new image. The second `run` already has them – no re-upload needed.

## How pending files work

Pending files accumulate until the next `contree run`:

1. Each `file edit` or `file cp` records a pending file in the session
2. When you run `contree run`, all pending files are merged into the payload
3. After the run completes, the new image already contains those files
4. The pending queue is effectively cleared (a new history checkpoint is
   created past them)

Explicit `--file` flags on `contree run` take priority over pending files
at the same path.

Pending files are branch-aware – switching branches with
`contree session checkout` changes which pending files are visible.

## Deduplication

Files are uploaded to the API with SHA256 dedup. If the same file content
has already been uploaded (from a previous edit or a different session), it
is reused without re-uploading.

***

You can inject and edit files. Next: [Images & Tags](./images).


# Your First Sandbox
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/first-steps



Now that you’re authenticated, let’s spin up a sandbox and explore it.

## Browse images

List available images:

<CodeGroup>
  ```bash CLI theme={null}
  contree images --prefix=ubuntu
  ```

  ```text Shell theme={null}
  contree images --prefix=ubuntu
  ```
</CodeGroup>

## Sessions

Every command in ConTree runs inside a **session** — a named workspace
that tracks which image you’re on, your working directory, file uploads,
and full branch/rollback history.

### How sessions are picked

You don’t have to create a session manually. When you run any command,
ConTree auto-generates a session key from your profile, parent process
ID, and terminal (TTY). This means the same terminal window gets the
same session — but **opening a new terminal creates a new session**
because the process ID changes.

There are three ways to control which session is used (in priority order):

1. **`-S` flag** — `contree -S my-session run ...` — explicit, survives terminal restarts
2. **`CONTREE_SESSION` env var** — `export CONTREE_SESSION=my-session` — stable for the shell session
3. **Auto-generated** — derived from profile + PID + TTY (default, tied to current terminal)

### Starting a session

The recommended way is `eval`, which exports the session key so it
survives across commands and is easy to resume later:

```bash theme={null}
eval $(contree use tag:ubuntu:latest)
```

Without `eval`, `contree use` still works within the same terminal —
the auto-generated key is stable as long as the terminal stays open:

```bash theme={null}
contree use tag:ubuntu:latest    # sets image
contree run uname -a             # same session (same terminal)
```

But if you close the terminal and open a new one, the auto-generated
session key changes. To resume a previous session, use `eval` or `-S`.

### Resuming sessions

List existing sessions and resume one:

```bash theme={null}
contree session list             # find the session key
contree -S my-project+a1b2c3d4 use   # resume it
```

Or pin a human-readable name from the start:

```bash theme={null}
contree -S build use tag:ubuntu:latest
contree -S build run -- make test
# close terminal, open new one — same session:
contree -S build run -- make deploy
```

<Tip>
  For agent workflows or scripts, always use `-S`:

  ```bash theme={null}
  contree -S build-agent use tag:ubuntu:latest
  contree -S build-agent run -- make build
  contree -S build-agent run -- make test
  ```

  This is the most reliable — no `eval`, no terminal dependency.
</Tip>

Inside `contree shell`, you don’t need `eval` — but the shell still
needs a session. Use `-S` or `CONTREE_SESSION` to pin it:

```bash theme={null}
contree -S my-project shell
```

Without `-S`, the auto-generated session is used (tied to current terminal).

## Run a command

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run uname -a
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    uname -a
    ```

    Bare commands are executed as implicit `run` in the sandbox.
    `contree run uname -a` works too – use the explicit form when you need
    flags like `-D`, `-e`, or `--file`.
  </Tab>
</Tabs>

The CLI spawns a sandbox, waits for it to finish, and prints stdout/stderr.
The resulting filesystem becomes the new session image – every non-disposable
run produces a new checkpoint.

<Tip>
  The `--` separator is optional. ConTree parses its own flags correctly
  regardless. It is a useful convention to visually separate contree options
  from the sandbox command:

  ```bash theme={null}
  contree run -D -- apt-get install -y curl
  ```

  Both `contree run uname -a` and `contree run -- uname -a` work the same way.
</Tip>

## Check session status

See what image and session you’re working with:

<CodeGroup>
  ```bash CLI theme={null}
  contree use
  ```

  ```text Shell theme={null}
  contree use
  ```
</CodeGroup>

Running `contree use` without arguments prints the current session info.

## Install packages

Commands chain naturally. Each run advances the session image:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run apt-get update -qq
    contree run apt-get install -y curl
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    apt-get update -qq
    apt-get install -y curl
    ```

    Or equivalently with the explicit prefix:

    ```text theme={null}
    contree run apt-get update -qq
    contree run apt-get install -y curl
    ```
  </Tab>
</Tabs>

After these two runs the session image includes `curl`.

## Change working directory

Set a working directory for the session — subsequent commands resolve
relative paths against it:

```bash theme={null}
contree cd /app
contree run -- ls            # lists /app
contree cat README.md        # reads /app/README.md
contree cd                   # reset to sandbox default
```

## Inspect the filesystem

List files and read content without spawning a new sandbox:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree ls /usr/bin
    contree cat /etc/os-release
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    ls /usr/bin
    cat /etc/os-release
    ```

    `ls` and `cat` are aliases for the contree API commands (no sandbox spawned).
    To run the actual instance commands instead, use the explicit prefix:

    ```text theme={null}
    contree run ls /usr/bin
    contree run cat /etc/os-release
    ```
  </Tab>
</Tabs>

## Download a file

Copy a file from the sandbox to your local machine:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree cp /etc/os-release ./os-release.txt
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree cp /etc/os-release ./os-release.txt
    ```

    There is no short alias for `cp` – use the full `contree cp` prefix.
  </Tab>
</Tabs>

## Disposable mode

Use `-D` / `--disposable` when you want to run a command without advancing the
session image. Changes are discarded after execution:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run -D -- rm -rf /important
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree run -D -- rm -rf /important
    ```

    Flags like `-D` require the explicit `contree run` prefix.
  </Tab>
</Tabs>

The session image stays exactly where it was before this run.

***

Your session tracks every command. Next: [Interactive Shell](./shell).


# Images & Tags
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/images



Images are filesystem snapshots. Every non-disposable `contree run`
produces a new image. Tags give images human-readable names so you
can find and reuse them later.

All data — images, operations, and uploaded files — is scoped to a
**Project**. Multiple tokens can access the same project and share
its data. Different projects have separate scopes — nothing is
visible across project boundaries.

## Listing images

Show tagged images:

```bash theme={null}
contree images
```

Filter by tag prefix:

```bash theme={null}
contree images --prefix=ubuntu
contree images --prefix=my-app
```

Include untagged images:

```bash theme={null}
contree images -a
```

Filter by time:

```bash theme={null}
contree images --since 1d        # last 24 hours
contree images --since 2025-04-01
```

## Tagging images

With one argument, tags the current session image. With two, the first
is the image reference:

```bash theme={null}
contree tag my-app:v1.0                      # current session image
contree tag UUID my-app:v1.0                 # specific image by UUID
contree tag tag:alpine:latest my-alpine      # re-tag by reference
```

The CLI resolves tag references to UUIDs automatically — you don’t
need to look up the UUID first.

Tags follow a free-form `name:version` convention. Common patterns:

```bash theme={null}
contree tag UUID my-app:latest
contree tag UUID my-app:v2.0
contree tag UUID common/python-ml/python:3.11-slim
```

Remove a tag:

```bash theme={null}
contree tag -U UUID my-app:v1.0
```

### Tag rules

* Tags are scoped to your Project (API token)
* Each image can have multiple tags
* Tags are unique — assigning an existing tag to a different image **moves** it
* Allowed characters: `a-z`, `0-9`, `_`, `-`, with `:`, `/`, `.` as separators
* Max length: 256 characters
* Case-sensitive (lowercase recommended)

### Shadow behavior

Public images (like `ubuntu:latest`) have their own tags. When you assign
the same tag to your own image, the public image is still accessible by
UUID but its tag becomes shadowed. Removing your tag restores the public
one.

## Using tags

Use `tag:NAME` anywhere an image UUID is expected:

```bash theme={null}
contree use tag:my-app:latest
```

If both you and a public image share a tag, your image wins.

## Importing images

Pull images from container registries (Docker Hub, GHCR, etc.):

```bash theme={null}
contree images import ubuntu:latest
contree images import --timeout 600 ubuntu:latest
contree images import python:3.11-slim
contree images import ghcr.io/org/repo:tag
```

Import is asynchronous — the CLI polls until the operation completes.
Press Ctrl+C to cancel.

Import multiple at once:

```bash theme={null}
contree images import ubuntu:latest python:3.11-slim node:20-slim
```

### Private registries

Authenticate with `--username`:

```bash theme={null}
contree images import --username=user registry.example.com/image:tag
```

The password is prompted securely if `--username` is provided.
Credentials are used only for the import operation and discarded
immediately after — the server does not store them.

## Reusing images across sessions

A common workflow is to prepare a base environment, tag it, and
reuse it in future sessions:

```bash theme={null}
# Session 1: build the environment
contree use tag:ubuntu:latest
contree run apt-get update -qq
contree run apt-get install -y python3 python3-pip build-essential
contree tag UUID python-dev:latest

# Session 2 (days later): start from the prepared image
contree use tag:python-dev:latest
contree run pip install -r requirements.txt
```

<Tip>
  Search for existing tagged images before rebuilding:

  ```bash theme={null}
  contree images --prefix=python-dev
  ```
</Tip>

***

Images are your checkpoints. Next: [Building from a Dockerfile](./build).


# Tutorial
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/index



Learn contree-cli by building a real workflow – from zero to automated
scripting in nine short sections.

## What you’ll build

By the end of this tutorial you will:

* Spin up sandboxes from images and run arbitrary commands
* Track sandbox state through sessions with branching and rollback
* Inject local files, edit remote configs, and tag working images
* Script everything with JSON output, detached runs, and operation monitoring

## Before you start

You need two things:

* **Python 3.10+** installed on your machine
* **A ConTree API token** — get one from your [project dashboard](https://contree.dev)

## The path

<Columns>
  <Card title="1. Install & Authenticate" href="./installation" icon="download">
    Install contree-cli, save your API token, and set up named profiles for
    different environments.
  </Card>

  <Card title="2. Your First Sandbox" href="./first-steps" icon="rocket">
    Browse images, run commands, inspect the filesystem, and download files.
    Understand how each run creates a new checkpoint.
  </Card>

  <Card title="3. Interactive Shell" href="./shell" icon="terminal">
    Use the REPL for rapid iteration: tab completion for paths, images, and
    branches, command aliases, and persistent history.
  </Card>

  <Card title="4. Sessions & Branches" href="./sessions" icon="code-branch">
    Branch off to experiment, roll back mistakes, share sessions across
    terminals, and start fresh when needed.
  </Card>

  <Card title="5. Working with Files" href="./files" icon="folder-open">
    Inject local code into sandboxes, edit remote files in-place, and stage
    changes that auto-attach on the next run.
  </Card>

  <Card title="6. Images & Tags" href="./images" icon="layer-group">
    Tag working images for reuse, import from registries, and search by
    prefix. Build reusable base environments.
  </Card>

  <Card title="7. Building from a Dockerfile" href="./build" icon="hammer">
    Turn a `Dockerfile` into a tagged ConTree image. Layer caching,
    build args, `.dockerignore`, and URL streaming for `ADD`.
  </Card>

  <Card title="8. Scripting & Automation" href="./workflows" icon="gears">
    Shell mode, shebang scripts, detached runs, operation monitoring, and
    machine-readable output formats for pipelines.
  </Card>

  <Card title="9. Configuration & Profiles" href="./configuration" icon="gear">
    Create and switch between profiles for different projects, understand
    how profiles affect sessions, and configure environment variables.
  </Card>
</Columns>

## Quick taste

If you just want to see contree-cli in action before diving in:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # install
    git clone https://github.com/nebius/contree-cli.git
    cd contree-cli && uv sync

    # authenticate (token prompted securely)
    contree auth

    # start a session and run a command
    eval $(contree use tag:ubuntu:latest)
    contree run uname -a

    # inspect the result
    contree ls /
    contree cat /etc/os-release
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={null}
    # install and authenticate first (see CLI tab)
    contree auth

    # start the interactive shell
    contree shell
    ```

    Once inside the shell:

    ```text theme={null}
    contree use tag:ubuntu:latest
    uname -a
    ls /
    cat /etc/os-release
    ```
  </Tab>
</Tabs>

Ready? Start with [Install & Authenticate](./installation).


# Install & Authenticate
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/installation



## Requirements

* Python 3.10 or later
* The `contree-client` library (installed automatically)

## Install

<CodeGroup>
  ```bash uv (recommended) theme={null}
  uv tool install contree-cli
  ```

  ```bash pip theme={null}
  pip install contree-cli
  ```

  ```bash pipx theme={null}
  pipx install contree-cli
  ```

  ```bash From source theme={null}
  git clone https://github.com/nebius/contree-cli.git
  cd contree-cli
  uv sync
  ```
</CodeGroup>

Verify the installation:

```bash theme={null}
contree --help
```

### Development setup

To work on contree-cli itself:

```bash theme={null}
git clone https://github.com/nebius/contree-cli.git
cd contree-cli
uv sync --group dev
make check    # lint + type check
make tests    # lint + type check + pytest
```

## Authenticate

All ConTree API calls require a bearer token and a project ID.

### Save credentials

Get an API token and project ID from your ConTree project, then save them:

```bash theme={null}
contree auth
```

You will be prompted to enter:

1. **Token** — entered securely (no echo)
2. **Project ID** — your project identifier

The CLI verifies the token with the API and writes credentials to
`~/.config/contree/auth.ini`. If a profile already exists you will be
prompted to confirm; use `-y` to skip the prompt.

Resolution order for each field during `contree auth` (first match wins):

1. CLI flag (`--token`, `--url`, `--project`)
2. Environment variables, in order:

   * token: `CONTREE_TOKEN`, then `NEBIUS_API_KEY`
   * URL: `CONTREE_URL`
   * project: `CONTREE_PROJECT`, then `NEBIUS_AI_PROJECT`
3. Interactive prompt

So if these variables are already in your environment and no flags
are passed, `contree auth` picks them up automatically, no interactive
prompts needed:

```bash theme={null}
export NEBIUS_API_KEY=eyJ...
export NEBIUS_AI_PROJECT=your-project-id
contree auth -y      # fully non-interactive
```

<Warning>
  Avoid `contree auth --token=eyJ...` — the token is visible in process
  listings and shell history. Omit `--token` to use the secure prompt.
</Warning>

### Named profiles

Store multiple tokens for different projects or environments:

```bash theme={null}
contree auth --profile=personal
contree auth --profile=sandbox
```

List all profiles:

```bash theme={null}
contree auth ls
```

Switch the active profile permanently:

```bash theme={null}
contree auth switch personal
```

Or use a profile temporarily (single session, no config change):

```bash theme={null}
export CONTREE_PROFILE=personal
contree images    # uses personal
```

### Token from environment

`CONTREE_TOKEN` and `NEBIUS_API_KEY` are read **only** by `contree auth`
during profile registration; runtime commands always read credentials
from the saved profile. To bootstrap a profile entirely from environment
variables, run `auth` non-interactively:

```bash theme={null}
export CONTREE_TOKEN=eyJ...
export CONTREE_URL=https://api.tokenfactory.nebius.com/sandboxes
contree auth -y --type jwt          # one-shot setup, no prompts
contree images
```

### Inline token

Pass `--token` to any command to override the saved profile for a single
invocation:

```bash theme={null}
contree --token=eyJ... images
```

***

You’re authenticated. Next: [Your First Sandbox](./first-steps).


# Sessions, Branches & Rollback
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/sessions



Sessions track the current image and its history as you run commands. Every
non-disposable `contree run` produces a new image, and the session records
the chain. Sessions also support **branching** and **rollback** for
experimentation.

## Session key

Every session is identified by a **session key** – an arbitrary string.
The CLI computes one automatically so that each terminal window gets its
own session without any extra setup.

The auto-generated key is a deterministic UUID5 derived from three values:

| Component | Source                               | Purpose                         |
| --------- | ------------------------------------ | ------------------------------- |
| `profile` | Active config profile name           | Isolates sessions per profile   |
| `ppid`    | Parent process ID (`os.getppid()`)   | The shell that launched the CLI |
| `tty`     | TTY device of stdin (`os.ttyname()`) | Distinguishes terminal windows  |

**In practice this means:**

* Open a new terminal tab – new `ppid` + `tty` – **new session**.
* Run `contree` commands in the same terminal – same `ppid` + `tty` –
  **same session** (resumes where you left off).
* Switch profiles – different `profile` – **new session**.

## Viewing session state

<CodeGroup>
  ```bash CLI theme={null}
  contree session            # show current session info
  contree session list       # list all sessions
  contree session show       # show full history DAG
  ```

  ```text Shell theme={null}
  contree session
  contree session list
  contree session show
  ```
</CodeGroup>

## Branching

Create a branch to experiment without affecting the main line:

<CodeGroup>
  ```bash CLI theme={null}
  contree session branch experiment
  contree session checkout experiment
  contree run apt-get install -y curl
  ```

  ```text Shell theme={null}
  contree session branch experiment
  contree session checkout experiment
  apt-get install -y curl
  ```
</CodeGroup>

Not happy? Switch back:

<CodeGroup>
  ```bash CLI theme={null}
  contree session checkout main
  ```

  ```text Shell theme={null}
  contree session checkout main
  ```
</CodeGroup>

Branches share history entries – creating a branch just creates a new
pointer at the current position.

Create a branch from another branch:

<CodeGroup>
  ```bash CLI theme={null}
  contree session branch hotfix --from main
  ```

  ```text Shell theme={null}
  contree session branch hotfix --from main
  ```
</CodeGroup>

List branches (`*` marks the active one):

<CodeGroup>
  ```bash CLI theme={null}
  contree session branch
  ```

  ```text Shell theme={null}
  contree session branch
  ```
</CodeGroup>

## Rollback

Move the branch pointer in the history chain. The argument distinguishes
absolute jumps from relative navigation:

| Argument            | Meaning                                                              |
| ------------------- | -------------------------------------------------------------------- |
| *(none)*            | Back one entry (default)                                             |
| `-- -N`             | Back N entries (the `--` stops argparse from parsing `-N` as a flag) |
| `+N`                | Forward N entries                                                    |
| `N` (bare positive) | **Absolute** jump to history id `N`                                  |

<CodeGroup>
  ```bash CLI theme={null}
  contree session rollback           # back one entry
  contree session rollback -- -3     # back three entries
  contree session rollback +1        # forward one entry
  contree session rollback 42        # absolute jump to history id 42
  ```

  ```text Shell theme={null}
  contree session rollback
  contree session rollback -- -3
  contree session rollback +1
  contree session rollback 42
  ```
</CodeGroup>

<Warning>
  A bare positive number is an **absolute** history id, not “back N steps”.
  Use `--` followed by a negative number for relative back-navigation.
  Inspect with `contree session show` first to avoid surprise jumps.
</Warning>

The history entries still exist and can be recovered by creating a branch at
a specific point.

## Starting a fresh session

Because the auto-generated key is deterministic, the same terminal always
resumes the same session. Use `--new` (`-N`) to start a fresh session:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # bash / zsh
    eval $(contree use -N tag:python:3.11-slim)

    # fish
    eval (contree use -N tag:python:3.11-slim)
    ```

    Without `eval`, the new session is **not active** until you export the
    printed variable into your shell. You can also copy-paste the `export`
    (or `set -gx`) line that `contree use` prints.
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree use -N tag:python:3.11-slim
    ```

    Inside the interactive shell, no `eval` is needed – the new session is
    activated automatically.
  </Tab>
</Tabs>

You can also set `CONTREE_SESSION` to any string:

```bash theme={null}
export CONTREE_SESSION=tutorial
contree use tag:python:3.11-slim
```

Unset it to go back to the automatic key:

```bash theme={null}
unset CONTREE_SESSION
```

## Sharing a session across terminals

`contree use` prints the session key. Export it in another terminal to
attach to the same session:

```bash theme={null}
# Terminal 1
contree use tag:ubuntu:latest
# output: export CONTREE_SESSION=<key>

# Terminal 2 -- paste the line above
export CONTREE_SESSION=<key>
contree run ls /     # operates on the same session
```

<Note>
  This pattern is CLI-only. The interactive shell manages sessions internally
  and does not require manual session key export.
</Note>

## Storage

Session data is stored in a per-profile SQLite database at
`~/.config/contree/sessions-{profile}.db`. Override the data
directory with `CONTREE_HOME`:

```bash theme={null}
export CONTREE_HOME=/tmp/contree-data
```

***

You can experiment freely with branches. Next: [Working with Files](./files).


# Interactive Shell
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/shell



`contree shell` starts a REPL that combines management commands and sandbox
execution in a single session. It is the fastest way to explore images, run
commands, edit files, and manage branches – all without leaving the prompt.

## Starting the shell

The shell needs a session, just like any other command. You can pin one
explicitly or let it auto-generate:

```bash theme={null}
contree -S my-project shell               # explicit session name
CONTREE_SESSION=my-project contree shell   # same via env var
contree shell                              # auto-generated (tied to terminal)
```

The shell prints a coloured prompt showing the current working directory:

```text theme={null}
contree interactive shell (type 'help' for commands, Ctrl-D to exit)
contree:/>
```

If the session already has an image (from a previous `contree use`), the
shell resumes it. Otherwise, set one first:

```text theme={null}
contree:/> contree use tag:ubuntu:latest
```

## Running commands

Type any command and it runs inside the sandbox:

```text theme={null}
contree:/> apt-get update -qq
contree:/> apt-get install -y curl
contree:/> curl https://example.com
```

Each command is an implicit `contree run` with `shell=True`. The whole
input line is forwarded verbatim to the remote `sh -c`, so pipes,
redirects, `;`, `&&`, and `||` are interpreted by the sandbox shell
exactly as typed:

```text theme={null}
contree:/> echo hello && ls / | head -5
contree:/> mount | grep cgroup
contree:/> echo 1 ; echo 2
contree:/> uname -a > /tmp/info.txt
```

Quoting from your local prompt is also preserved through to the remote
shell:

```text theme={null}
contree:/> python3 -c "print('hello world')"
```

You can also use the explicit form, which is equivalent:

```text theme={null}
contree:/> contree run apt-get install -y curl
```

The explicit `contree run` prefix is required when you need flags like
`-D` (disposable), `-e` (env), `-t` (timeout), `--file`, or `-d` (detach):

```text theme={null}
contree:/> contree run -D -- rm -rf /tmp/*
contree:/> contree run -e DEBUG=1 -- ./app
contree:/> contree run -d -- long-running-task
```

## Tab completion

The shell supports context-aware tab completion for nearly everything.
Press Tab at any point to see available completions.

### What completes

**Commands and subcommands** – type `contree` then Tab to see all
available subcommands. Type a partial name and Tab completes it:

```text theme={null}
contree:/> contree ses<TAB>
contree:/> contree session <TAB>
branch  checkout  list  rollback  show  use
```

**Flags** – type `-` or `--` after a command and Tab shows available
flags:

```text theme={null}
contree:/> contree run --<TAB>
--cwd  --detach  --disposable  --env  --file  --hostname ...
```

**Sandbox paths** – any command that takes a file path completes
against the actual sandbox filesystem. The shell queries the image
via the inspect API and caches the results:

```text theme={null}
contree:/> ls /etc/<TAB>
apt/       bash.bashrc  default/   hostname   nginx/     passwd ...

contree:/> cat /etc/os-<TAB>
contree:/> cat /etc/os-release

contree:/> vim /etc/nginx/<TAB>
nginx.conf  sites-enabled/
```

**Directory-only paths** – `cd` completes only directories:

```text theme={null}
contree:/> cd /us<TAB>
contree:/> cd /usr/<TAB>
bin/  include/  lib/  local/  sbin/  share/
```

**Images** – `contree use` and `contree tag` complete image references.
Type `tag:` to filter by tag names, or start typing a UUID:

```text theme={null}
contree:/> contree use tag:<TAB>
tag:ubuntu:latest  tag:python:3.11-slim  tag:common/rust/ubuntu:noble ...

contree:/> contree use tag:py<TAB>
contree:/> contree use tag:python:3.11-slim
```

**Operations** – `contree show` and `contree kill` complete operation
UUIDs:

```text theme={null}
contree:/> contree show <TAB>
a1b2c3d4-...  e5f6a7b8-...
```

**Branches and sessions** – session management subcommands complete
branch names and session keys:

```text theme={null}
contree:/> contree session checkout <TAB>
main  experiment  hotfix

contree:/> contree session use <TAB>
abc123_def456  tutorial  ci-build-42
```

**Help topics** – `help` completes all command and alias names:

```text theme={null}
contree:/> help <TAB>
cat  cd  contree  exit  help  history  ls  nano  pwd  quit  vim ...
```

### What does not complete

**Bare commands** (implicit `run`) do not have tab completion. The shell
does not know what executables exist inside the sandbox, so typing a
bare command name and pressing Tab will not offer suggestions:

```text theme={null}
contree:/> apt-g<TAB>     # no completion
contree:/> pyth<TAB>      # no completion
```

However, paths starting with `/` do complete even in bare command context:

```text theme={null}
contree:/> python /app/<TAB>
main.py  utils.py  config.yaml
```

## Aliases

The shell intercepts several bare command names for convenience:

### `ls` and `cat`

Bare `ls` and `cat` are forwarded as contree API commands – they inspect
the sandbox filesystem without spawning a new instance:

```text theme={null}
contree:/> ls /etc
contree:/> cat /etc/os-release
```

This is equivalent to `contree ls` and `contree cat`. To run the actual
`ls` or `cat` binary inside the sandbox instead, use the explicit prefix:

```text theme={null}
contree:/> contree run ls -la /etc
contree:/> contree run cat -n /etc/os-release
```

<Note>
  When pending files exist (from `contree file edit` or `contree file cp`),
  `ls` and `cat` automatically fall back to running inside the sandbox so
  the pending files are visible.

  The same fallback happens when arguments contain flags (`-l`) or glob
  characters (`*`, `?`, `[`).
</Note>

### `vim`, `vi`, `nvim`, `nano`

Editor names open `contree file edit` with the corresponding host editor:

```text theme={null}
contree:/> vim /etc/nginx/nginx.conf
```

This downloads the file, opens it in vim on your machine, and stages any
changes as a pending file for the next run.

## Builtins

### `cd`

Change the working directory for subsequent commands:

```text theme={null}
contree:/> cd /app
contree:/app> python main.py

contree:/app> cd -        # go back to previous directory
contree:/>
```

`cd` without arguments resets to the sandbox’s default working directory.

<Note>
  `cd` does not validate that the path exists in the sandbox. Errors
  surface only when the next command uses the invalid path.
</Note>

### `pwd`

Print the current working directory:

```text theme={null}
contree:/app> pwd
/app
```

### `history`

Show command history for the current session, optionally filtered by a
case-insensitive substring:

```text theme={null}
contree:/> history                 # show all entries
contree:/> history apt             # only lines containing "apt"
contree:/> history 'contree '      # quoted match (note trailing space)
```

History is persisted in SQLite per session (up to 10,000 lines) and
restored when you re-enter the shell. Search is scoped to the current
session key; different sessions have isolated history.

### `help`

Show general shell help, or help for a specific command or builtin:

```text theme={null}
contree:/> help
contree:/> help cd
contree:/> help run
```

Bare `help` prints an overview of builtins, aliases, line continuation,
and tab completion. `help <topic>` shows detailed help for a builtin,
alias, or contree command.

### `clear`

Clear the terminal screen:

```text theme={null}
contree:/> clear
```

### `timeout`

Run a command with a server-enforced operation timeout. Mirrors the GNU
`timeout` convention but sets `payload.timeout` on the API request instead
of spawning a local wrapper inside the sandbox:

```text theme={null}
contree:/> timeout 30 apk add gcc
contree:/> timeout 5m make build
contree:/> timeout 1h python long_train.py
```

`DURATION` accepts a bare integer or decimal (seconds by default) and
the suffixes `s`, `m`, `h`, `d`. When the value cannot be parsed, the
shell forwards the line untouched so the in-image `timeout` binary still
handles advanced flags like `--kill-after` or `-s SIGTERM`.

When the limit fires, the API returns `state.timed_out=true` (status may
still be `SUCCESS` with `signal=9`), and the shell logs:

```text theme={null}
WARNING: Operation <uuid> timed out after 30s
```

### `--format` / `-f`

Change the output format mid-session, or show the current format:

```text theme={null}
contree:/> --format json   # switch to JSON output
contree:/> -o table        # switch to table output
contree:/> --format        # show current format name
```

## Workflow example

A typical shell session putting it all together:

```text theme={null}
contree:/> contree use tag:ubuntu:latest
contree:/> apt-get update -qq
contree:/> apt-get install -y python3 python3-pip
contree:/> contree file cp ./app.py /app/app.py
contree:/> contree file cp ./requirements.txt /app/requirements.txt
contree:/> cd /app
contree:/app> pip install -r requirements.txt
contree:/app> python3 app.py
contree:/app> vim app.py                    # edit and re-run
contree:/app> python3 app.py
contree:/app> contree session branch stable
contree:/app> contree tag UUID my-app:v1
```

## Limitations

* **Output format is fixed** – the `--format` flag is set at `contree shell`
  launch. To use JSON output: `contree -o json shell`.
* **No local pipes or redirects** – `|`, `>`, `<` are sent to the sandbox,
  not interpreted locally.
* **No job control** – no `&`, `bg`, `fg`, or Ctrl-Z. Use `contree run -d`
  for detached execution.
* **Bare commands use defaults** – you cannot pass `--env`, `--file`, or
  `--disposable` without the explicit `contree run` prefix. The operation
  timeout has a shell shortcut: `timeout DURATION CMD...` (see above).
* **No `~` or glob expansion** – these tokens are passed as-is to the
  sandbox.
* **Image list cache** – newly created images during a session won’t appear
  in tab completion until the shell is restarted. Path completions are
  cached per image and refresh when the session image advances.

***

The shell is the fastest way to iterate. Next: [Sessions, Branches & Rollback](./sessions).


# Scripting & Automation
Source: https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/workflows



contree-cli is designed for scripting. Exit codes propagate, output formats
are machine-readable, and shebang mode lets you write executable sandbox
scripts.

## Shebang scripts

<Note>
  Shebang scripts are a CLI-only feature. They are not available in the
  interactive shell.
</Note>

Any file with a `contree run -I` shebang runs inside a sandbox:

```bash theme={null}
#!/usr/bin/env -S contree run -I
echo "Hello from a ConTree sandbox"
uname -a
```

Save it, `chmod +x`, and run it directly:

```bash theme={null}
chmod +x hello.sh
./hello.sh
```

The `-I` (interpreter) flag reads the script, strips the shebang line, and
sends the body as stdin to `/bin/sh -s` inside the sandbox.

### Combining flags

Shebang flags stack. A disposable run with a 10-second timeout:

```bash theme={null}
#!/usr/bin/env -S contree run -I -D -t 10
apt-get update -qq
apt-get install -y curl
curl https://example.com
```

Since `-D` is set, the session image is not advanced – the script runs in
a throwaway sandbox.

### Passing arguments

Extra arguments after the script name are forwarded to the shell:

```bash theme={null}
#!/usr/bin/env -S contree run -I
echo "arg1=$1 arg2=$2"
```

```bash theme={null}
./script.sh foo bar
# arg1=foo arg2=bar
```

<Note>
  The `-S` flag on `/usr/bin/env` is required because the `contree` entry point
  is a Python script. Without `-S`, the kernel sees a nested shebang
  (script -> script -> binary) and returns ENOEXEC. Using `/usr/bin/env -S`
  (a real binary) splits the argument string and avoids this.
</Note>

## Execution modes

### Direct command

The default mode. Each positional argument becomes a separate argv entry:

<CodeGroup>
  ```bash CLI theme={null}
  contree run uname -a
  ```

  ```text Shell theme={null}
  uname -a
  ```
</CodeGroup>

### Shell mode

`-s` joins all arguments into a single shell expression:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run -s -- 'echo hello && ls /'
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    echo hello && ls /
    ```

    Bare commands in the shell always use shell mode.
  </Tab>
</Tabs>

Useful when you need pipes, redirects, or `&&` chains.

### Piped stdin

<Note>
  Piped stdin is a CLI-only feature. It is not available in the interactive
  shell.
</Note>

When stdin is not a TTY, it is read, base64-encoded, and sent to the sandbox:

```bash theme={null}
echo 'uname -a' | contree run /bin/sh
```

```bash theme={null}
cat deploy.sh | contree run /bin/sh
```

### Detached mode

`-d` spawns the operation and exits immediately, printing the operation UUID:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run -d -- long-running-task
    ```

    Check on it later:

    ```bash theme={null}
    contree show UUID
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree run -d -- long-running-task
    contree show UUID
    ```

    Flags like `-d` require the explicit `contree run` prefix.
  </Tab>
</Tabs>

## Exit codes

<Note>
  Exit code propagation is a CLI-only feature useful for scripting. The
  interactive shell does not expose sandbox exit codes.
</Note>

The sandbox exit code propagates to the CLI process:

```bash theme={null}
contree run -- /bin/sh -c 'exit 42'
echo $?    # 42
```

This means `contree run` works naturally in `if`, `&&`, `||`, and `set -e`
scripts:

```bash theme={null}
set -e
contree run -- make test          # script aborts if tests fail
contree run -- make install
```

If the operation fails at the platform level (timeout, cancelled), the CLI
exits with code 1.

## Environment variables

Pass environment variables into the sandbox with `-e`:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    contree run -e DEBUG=1 -e DB_HOST=postgres -- ./app
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree run -e DEBUG=1 -e DB_HOST=postgres -- ./app
    ```

    Flags like `-e` require the explicit `contree run` prefix.
  </Tab>
</Tabs>

The flag is repeatable. Format is `KEY=VALUE`.

## Output truncation

By default, stdout/stderr is capped at 64 KiB in the API response. Override
with `-T`:

<CodeGroup>
  ```bash CLI theme={null}
  contree run -T 1048576 -- ./generate-big-output.sh
  ```

  ```text Shell theme={null}
  contree run -T 1048576 -- ./generate-big-output.sh
  ```
</CodeGroup>

## Monitor operations

List running and recent operations:

<CodeGroup>
  ```bash CLI theme={null}
  contree ps            # active operations only
  contree ps -a         # all (including completed)
  contree ps -q         # UUIDs only, one per line
  ```

  ```text Shell theme={null}
  contree ps
  contree ps -a
  contree ps -q
  ```
</CodeGroup>

Show the full result of a specific operation:

<CodeGroup>
  ```bash CLI theme={null}
  contree show UUID
  ```

  ```text Shell theme={null}
  contree show UUID
  ```
</CodeGroup>

Cancel an operation:

<CodeGroup>
  ```bash CLI theme={null}
  contree kill UUID
  contree kill --all
  ```

  ```text Shell theme={null}
  contree kill UUID
  contree kill --all
  ```
</CodeGroup>

### Fan-out + wait

When several independent steps can run at the same time, spawn each
one detached and join them with `contree op wait` (alias `contree operation wait`). The wait command polls the API and prints one row
per operation as soon as it reaches a terminal status, with columns
`uuid`, `status`, `exit_code`, `timed_out`, `duration`, and any other
scalar field the API returns. The `status` column is the server’s
verdict (did the API run the job?) and is reported verbatim; the
sandbox process’s own exit code is in the separate `exit_code` column.
The CLI exit status is `1` when any op finished non-`SUCCESS`, or the
actual `exit_code` when a `SUCCESS` op exited non-zero, so the wait
still composes naturally with `&&`.

<Info>
  `op wait` is a **pure observer** — it polls completion status but
  **does not touch local session state**. That makes the pattern most
  natural with `--disposable` (no image to track). For non-disposable
  fan-out, the result images live only on the server; the
  `detached-<op-uuid>` branches created at spawn time still point at
  the **starting** image and never get moved. See the non-disposable
  recovery example below.
</Info>

The preferred shape — disposable runs, parallel independent checks.
The global `-o json` must come BEFORE the subcommand so that `jq`
gets JSON; the default `run -d` formatter is plain.

```bash theme={null}
# Three parallel test suites, results discarded after the runs
A=$(contree -o json run -d --disposable -- pytest tests/a | jq -r .uuid)
B=$(contree -o json run -d --disposable -- pytest tests/b | jq -r .uuid)
C=$(contree -o json run -d --disposable -- pytest tests/c | jq -r .uuid)

# Block until each one finishes (or 60 s elapses, whichever comes first)
contree op wait "$A" "$B" "$C"

# Inspect stdout/stderr per leg
contree op show "$A" "$B" "$C"
```

Non-disposable fan-out works too, but you have to recover the result
images yourself — `op wait` will not bind them into the session:

```bash theme={null}
A=$(contree -o json run -d -- apt-get install -y curl | jq -r .uuid)
B=$(contree -o json run -d -- apt-get install -y wget | jq -r .uuid)
contree op wait "$A" "$B"

# Pull the winning leg's image out of the operation result and
# attach it to the active session.
IMG_A=$(contree -o json op show "$A" | jq -r .image)
contree use "$IMG_A"

# Or tag it for reuse later.
contree tag "$IMG_A" feature/curl-tools
```

After fan-out + wait the session retains a `detached-<op-uuid>`
branch per spawn. They all point at the image that existed when the
fan-out started, so they are mostly cosmetic — feel free to delete
them with `contree session branch --prune` when you no longer need
them.

Useful flags:

* `--timeout SECONDS` — cap on the wait (default 60). If the deadline
  hits before every operation reaches a terminal status, `op wait`
  emits one extra row per unfinished op with `timed_out=true` and the
  operation’s last observed status (e.g. `EXECUTING`), then exits
  with status `1`.
* `--all` — wait for every currently active operation in the project,
  not just the ones you passed.

```bash theme={null}
# Block on every active op, up to 5 minutes
contree op wait --all --timeout 300
```

<Warning>
  `--all` is **project-scoped**. If multiple agents or shell sessions
  share the same project, `op wait --all` will block on every active
  operation across all of them — not just the ones you launched. For
  multi-agent or multi-shell setups prefer the explicit
  `op wait UUID1 UUID2 ...` form with the UUIDs you actually own.
</Warning>

`op wait` exits non-zero whenever any operation finished with a
non-`SUCCESS` status (so it composes naturally with shell `&&`
chains), even when no `--timeout` was hit.

```bash theme={null}
# Run fan-out + tests; bail if any leg failed
contree op wait "$A" "$B" "$C" && echo "all green" || echo "some failed"
```

### Scripting patterns

<Note>
  Shell piping and command substitution are CLI-only features. These patterns
  are not available in the interactive shell.
</Note>

Combine `-q` with other tools:

```bash theme={null}
# Show results of all active operations
contree ps -q | xargs -I {} contree show {}

# Kill all running operations
contree ps -q | xargs -I {} contree kill {}

# Launch detached, capture UUID
OP=$(contree run -d -- sleep 3600)
# ... do other work ...
contree show "$OP"
```

## Output formats

<Note>
  The `--format` flag is global and set at CLI launch time. In the interactive
  shell, the format is fixed for the entire session and cannot be changed
  mid-session.
</Note>

Use `-f` / `--format` to control output. The flag is global and goes
before the subcommand:

`default`
: Table-like output optimized for human reading. Some commands (like
`run`) use a custom default that prints only stdout/stderr.

`table`
: Aligned columns with headers. Identical to `default` for most commands.

`csv`
: Comma-separated values with a header row. Useful for spreadsheet import
or `cut`/`awk` processing.

`tsv`
: Tab-separated values with a header row. Works well with `column -t`.

`json`
: One JSON object per line (JSONL/NDJSON). Each output row is a separate
JSON object. Suitable for `jq` processing.

`json-pretty`
: All rows collected into a single pretty-printed JSON array. Output is
flushed at the end.

### Examples

```bash theme={null}
# Pipe JSON to jq
contree -o json ps | jq '.uuid'

# CSV for scripting
contree -o csv images > images.csv

# Tab-separated for column alignment
contree -o tsv ps | column -t

# Get image UUID from tag
contree -o json images --prefix=ubuntu | jq -r '.uuid'
```

### Streaming behavior

`json` and `json-pretty` formatters support streaming output from
commands like `run` and `show` – stdout/stderr are included in the
JSON payload.

`csv`, `tsv`, and `table` formatters do not include stdout/stderr
from sandbox execution. Use `default` or `json` formats to see
sandbox output.

## Session management in scripts

<Note>
  Script-level session management with `eval` and `CONTREE_SESSION` is a
  CLI-only pattern. The interactive shell manages sessions automatically.
</Note>

The `eval $(contree use ...)` pattern exports the session key into your
shell. In scripts, set `CONTREE_SESSION` explicitly to control which
session you operate on:

```bash theme={null}
#!/bin/bash
export CONTREE_SESSION=ci-build-$$
contree use tag:ubuntu:latest
contree run apt-get update -qq
contree run apt-get install -y build-essential
contree run --file ./src:/src make -C /src test
```

Using `$$` (PID) or a fixed name gives you a predictable, isolated session
per script run.

***

You now know the full CLI. Next: [Configuration & Profiles](./configuration).


# Cheatsheet
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/cheatsheet



Quick reference card for AI agents using Contree MCP.

## Tools at a Glance

| Tool               | When to Use                     | Cost |
| ------------------ | ------------------------------- | ---- |
| `list_images`      | Before importing anything       | Free |
| `import_image`     | Need new base image             | VM   |
| `rsync`            | Local files needed in container | Free |
| `run`              | Execute code                    | VM   |
| `upload`           | Single file to container        | Free |
| `download`         | Extract file from container     | Free |
| `get_image`        | Check if image exists           | Free |
| `set_tag`          | Name frequently-used images     | Free |
| `list_files`       | Explore container filesystem    | Free |
| `read_file`        | Read file from container        | Free |
| `get_operation`    | Poll async operation            | Free |
| `list_operations`  | Find running operations         | Free |
| `wait_operations`  | Wait for multiple ops           | Free |
| `cancel_operation` | Stop stuck operation            | Free |
| `get_guide`        | Get documentation sections      | Free |

## Common Workflows

### Run Python Code

```
1. list_images(tag_prefix="python")     → Check existing
2. import_image(docker://python:3.11)   → If needed
3. rsync(source="/project", dest="/app") → Sync files
4. run(cmd, image, ds_id)        → Execute
```

### Install Dependencies

```
1. run(pip install ..., disposable=false) → Save image
2. Use result_image for subsequent commands
```

### Parallel Execution

```
1. run(cmd1, wait=false) → op-1
2. run(cmd2, wait=false) → op-2
3. wait_operations([op-1, op-2])  → Get both results
```

### Rollback

```
1. Save last good image UUID
2. If something breaks, use the saved UUID
3. No cleanup needed—images are immutable
```

### Inspect Container (No VM)

```
1. list_files(image, path="/etc")    → List directory
2. read_file(image, path="/etc/os-release") → Read file
```

## Decision Quick Guide

| Situation                  | Action                               |
| -------------------------- | ------------------------------------ |
| First time using an image  | `list_images` first                  |
| Running existing code      | `rsync` + `run`                      |
| Installing packages        | `run` with `disposable=false`        |
| Multiple independent tasks | Use `wait=false` + `wait_operations` |
| Long-running command       | Increase `timeout`                   |
| Large output expected      | Increase `truncate_output_at`        |
| Need to save state         | `disposable=false`                   |
| One-off experiment         | `disposable=true` (default)          |

## Parameters Quick Reference

### run

```json theme={null}
{
  "command": "...",           // Required
  "image": "uuid",            // Required
  "directory_state_id": "ds-...", // From rsync
  "disposable": true,         // Discard changes (default)
  "timeout": 30,              // Seconds
  "env": {"KEY": "value"},    // Environment
  "wait": true                // Sync execution (default)
}
```

### rsync

```json theme={null}
{
  "source": "/local/path",    // Required
  "destination": "/container/path", // Required
  "exclude": ["__pycache__", ".git", ".venv", "node_modules"]
}
```

### import\_image

```json theme={null}
{
  "registry_url": "docker://image:tag", // Required
  "tag": "my-tag",            // Optional, for frequent reuse
  "wait": true                // Sync (default)
}
```

## Key Rules

1. **Check before importing** — `list_images` first
2. **Reuse directory\_state\_id** — Valid for entire session
3. **Use UUIDs directly** — Only tag frequently-used images
4. **One step per command** — Easier rollback and debugging
5. **Always exclude** — `__pycache__`, `.git`, `.venv`, `node_modules`

## Error Recovery

| Error                     | Solution                           |
| ------------------------- | ---------------------------------- |
| Image not found           | `list_images` to find correct UUID |
| Directory state not found | Re-run `rsync`                     |
| Command timed out         | Increase `timeout` parameter       |
| Output truncated          | Increase `truncate_output_at`      |
| Operation stuck           | `cancel_operation` + retry         |

## Resources (Read-Only)

| URI Pattern                          | Returns                  |
| ------------------------------------ | ------------------------ |
| `contree://image/{uuid}/read/{path}` | File contents            |
| `contree://image/{uuid}/ls/{path}`   | Directory listing        |
| `contree://image/{uuid}/lineage`     | Parent-child history     |
| `contree://guide/{section}`          | Documentation            |
| `contree://operations/instance/{id}` | Command execution result |
| `contree://operations/import/{id}`   | Image import result      |


# Core Concepts
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/concepts/core



How Contree runs code and manages container images.

## Execution Model

When you call `run`, Contree:

1. Spins up an isolated microVM (\~2-5 seconds)
2. Mounts the specified image as the filesystem
3. Injects any files from `directory_state_id` or `files`
4. Executes your command as root
5. Captures stdout, stderr, exit code
6. Optionally saves the resulting filesystem as a new image

**Isolation guarantees:** Every command runs in a separate kernel with full network/filesystem isolation. Destructive commands (`rm -rf /`, kernel exploits) are completely safe.

## The disposable Flag

| Setting          | Behavior          | Use Case                      |
| ---------------- | ----------------- | ----------------------------- |
| `true` (default) | Changes discarded | Tests, read-only operations   |
| `false`          | New image created | Installing packages, building |

**filesystem\_changed response field:**

* When `true`, `result_image` is a new UUID (changes were saved)
* When `false`, `result_image` equals input image (no snapshot created)

## Images

Every image is:

* **Immutable**: Once created, it never changes
* **Identified by UUID**: `abc123-def456-789012`
* **Optionally tagged**: Human-readable names like `python:3.11`

| Aspect      | UUID                         | Tag                                 |
| ----------- | ---------------------------- | ----------------------------------- |
| Immutable   | Yes                          | Points to different UUIDs over time |
| When to use | Chaining, one-off operations | Frequently reused base images       |

## Lineage

When you run with `disposable=false` and filesystem changes, Contree creates a parent-child relationship:

```
docker://alpine:latest (img-root)
    └── apk add python3 (img-with-python)
        ├── pip install numpy (img-with-numpy)
        └── pip install pandas (img-with-pandas)
```

**View lineage:**

```
contree://image/{uuid}/lineage
```

**Rollback:** Just use any ancestor UUID - no special command needed.

## Timeouts and Output

* **Default timeout**: 30 seconds (use `timeout` parameter for longer)
* **Default output limit**: 8000 bytes (\~2000 tokens)
* **Adjust with**: `truncate_output_at` parameter


# Concepts
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/concepts/index



Core ideas behind Contree MCP.

<Columns>
  <Card title="Core Concepts" href="./core" icon="layer-group" />

  <Card title="Workflows" href="./workflows" icon="diagram-project" />
</Columns>

## Overview

| Concept       | Description                                 |
| ------------- | ------------------------------------------- |
| **Core**      | Execution model, images, lineage, isolation |
| **Workflows** | File sync (rsync), async execution          |

## Quick Mental Model

```mermaid theme={null}
flowchart LR
    A[import_image] --> B[Base Image]
    B --> C[run<br/>disposable=false]
    C --> D[Child Image]
    D --> E[Another run]
    B --> F[Different branch]
```

Every image is immutable. `disposable=false` creates a new child image. Navigate and rollback using any ancestor UUID.


# Workflows
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/concepts/workflows



File sync and async execution patterns.

## File Sync

Two ways to inject files into containers:

| Method   | Use Case                        | Caching      |
| -------- | ------------------------------- | ------------ |
| `rsync`  | Directories, multiple files     | Yes (3-tier) |
| `upload` | Single files, generated content | No           |

### rsync (Preferred)

```json theme={null}
{"tool": "rsync", "args": {
  "source": "/project",
  "destination": "/app",
  "exclude": ["__pycache__", ".git", ".venv", "node_modules"]
}}
```

Returns `directory_state_id` for use in `run`.

**Three-tier caching**: Local cache → Cache by hash → Server dedup → Upload. Most files resolve from cache.

**Reuse across runs**: The `directory_state_id` is valid for the session. Only re-sync when files change.

### upload (Single Files)

```json theme={null}
{"tool": "upload", "args": {"content": "print('hello')"}}
```

Reference in `run` via `files` parameter:

```json theme={null}
{"files": {"/app/script.py": "file-uuid"}}
```

## Async Execution

| Mode  | Parameter             | Behavior                           |
| ----- | --------------------- | ---------------------------------- |
| Sync  | `wait=true` (default) | Blocks until complete              |
| Async | `wait=false`          | Returns `operation_id` immediately |

### Parallel Pattern

```json theme={null}
// Launch async
{"command": "python exp_a.py", "wait": false}  // Returns op-1
{"command": "python exp_b.py", "wait": false}  // Returns op-2
{"command": "python exp_c.py", "wait": false}  // Returns op-3

// Wait for all
{"tool": "wait_operations", "args": {"operation_ids": ["op-1", "op-2", "op-3"]}}
```

### wait\_operations Modes

* `"all"` - Wait for all operations to complete
* `"any"` - Return when first operation completes

### Operation States

| State       | Description            |
| ----------- | ---------------------- |
| `PENDING`   | Queued, not started    |
| `EXECUTING` | Running                |
| `SUCCESS`   | Completed successfully |
| `FAILED`    | Completed with error   |
| `CANCELLED` | Cancelled by user      |

### When to Use Async

**Use `wait=false`** when:

* Running 2+ independent operations
* Operations are long-running (>10s)

**Use `wait=true`** when:

* Running a single operation
* Operations must be sequential


# Overview
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/index



[![PyPI](https://img.shields.io/pypi/v/contree-mcp.svg)](https://pypi.org/project/contree-mcp/)
[![Tests](https://github.com/nebius/contree-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/nebius/contree-mcp/actions/workflows/tests.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/nebius/contree-mcp/blob/master/LICENSE)

**Isolated cloud container execution for AI agents.**

Contree MCP is a Model Context Protocol server that gives AI agents secure sandboxed environments with full root access, network, and persistent images. Experiment fearlessly—every container is isolated, every image is immutable, mistakes are free.

<Columns>
  <Card title="Quickstart" href="./quickstart" icon="rocket">
    Run your first container in 5 minutes.
  </Card>

  <Card title="Concepts" href="./concepts/index" icon="lightbulb">
    Understand execution model, images, file sync.
  </Card>

  <Card title="Tools" href="./tools/index" icon="screwdriver-wrench">
    All 15 tools with parameters and examples.
  </Card>

  <Card title="Patterns" href="./patterns" icon="shapes">
    Common workflows and mistakes to avoid.
  </Card>

  <Card title="Prompts" href="./prompts/index" icon="comments">
    10 MCP prompts for common workflows.
  </Card>
</Columns>

## Why Contree?

* **Safe sandbox**: Run `rm -rf /`, kernel exploits—nothing escapes
* **Immutable images**: Every UUID is a snapshot, branching is cheap
* **Instant rollback**: Revert to any previous image at zero cost

## Quick Example

```json theme={null}
{"tool": "list_images", "args": {"tag_prefix": "python"}}

{"tool": "rsync", "args": {"source": "/project", "destination": "/app"}}

{"tool": "run", "args": {
  "command": "python /app/main.py",
  "image": "img-uuid",
  "directory_state_id": "ds-uuid"
}}
```

## HTTP Mode

Run the MCP server with built-in interactive documentation:

```bash theme={null}
contree-mcp --mode http --http-port 9452
```

Visit `http://localhost:9452/` for setup guides, tool reference, and best practices.

<Frame>
  <img alt="Contree MCP Server HTTP interface" />
</Frame>

## Security

To report security issues, see [Security](./security).

## License

Licensed under the Apache License, Version 2.0. See LICENSE for details.


# Configuration
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/integration/configuration



Detailed configuration options for Contree MCP.

## Authentication

The MCP server supports both auth modes the Contree API exposes — the
same two `contree-cli` recognises:

* **IAM (recommended).** Token + Project header. Sends
  `Authorization: Bearer <iam-token>` and `Project: <project-id>`.
  Default URL: `https://api.tokenfactory.nebius.com/sandboxes`. Use this
  for new deployments; the standard `NEBIUS_API_KEY` /
  `NEBIUS_AI_PROJECT` env vars are honoured.
* **JWT (legacy).** Token only. Sends `Authorization: Bearer <jwt-token>`.
  Used by the `contree.dev` PoC deployment. No project required.

A profile’s `type = iam | jwt` line picks the scheme; the client class
that issues backend requests is wired accordingly at startup.

### Profile File (Recommended)

`contree-mcp` reads the same profile file that
[`contree-cli`](https://docs.contree.dev/cli/tutorial/installation.html)
writes, so a single login covers both tools. Install the CLI and run
`contree auth`:

```bash theme={null}
uv tool install contree-cli   # or: pip install contree-cli
contree auth                  # interactive setup
```

This writes `~/.config/contree/auth.ini` with mode `0600`. Override
the directory with `CONTREE_HOME`.

The file is INI-format with one `[profile:<name>]` section per
credential set and a `[DEFAULT] profile = <name>` line selecting the
active profile:

```ini theme={null}
[DEFAULT]
profile = default

[profile:default]
type = iam
url = https://api.tokenfactory.nebius.com/sandboxes
token = <TOKEN HERE>
project = <NEBIUS PROJECT ID>

[profile:staging]
type = jwt
url = https://contree.dev
token = <TOKEN HERE>
```

Switch profiles persistently with `contree auth switch <name>`, or
per-invocation with `--profile <name>` / `CONTREE_PROFILE=<name>`.

`type = iam` requires `project`; `type = jwt` does not.

### Environment Variables (Per-Invocation Overrides)

For one-off overrides without touching the profile file:

```bash theme={null}
export CONTREE_TOKEN="your-token-here"
export CONTREE_URL="https://api.tokenfactory.nebius.com/sandboxes"
export CONTREE_PROJECT="your-nebius-project-id"
```

The standard Nebius IAM credentials are recognised too:

```bash theme={null}
export NEBIUS_API_KEY="your-iam-key"
export NEBIUS_AI_PROJECT="your-nebius-project-id"
```

#### Precedence (important)

Field-by-field, highest first:

1. **CLI flags** — `--token`, `--project`, `--url`, `--profile`.
2. **`CONTREE_*` env vars** — `CONTREE_TOKEN` / `CONTREE_PROJECT` /
   `CONTREE_URL` / `CONTREE_PROFILE`. MCP-specific; always layered
   on top of the profile.
3. **`NEBIUS_*` env vars** — `NEBIUS_API_KEY` + `NEBIUS_AI_PROJECT`,
   recognised **only when both are set** (a complete IAM credential).
   A lone `NEBIUS_API_KEY` set ambiently for the Nebius SDK or
   terraform provider is **ignored**, and the MCP server logs an
   `info` line explaining why.
4. **Active profile** from `auth.ini`. Picked by, in order, `--profile`
   → `CONTREE_PROFILE` → the file’s `[DEFAULT] profile = ...`.

Some practical implications:

* `contree-mcp` (no args) loads the active profile, even if your shell
  has `NEBIUS_API_KEY` set for other tools.
* `CONTREE_TOKEN=NEW contree-mcp` rotates the token but reuses the
  profile’s `project` and `url` — handy for short-lived tokens.
* `contree-mcp --token X --project Y` populates token + project from
  the CLI; `url` and `auth_type` still come from the loaded profile
  unless `--url` / `--auth-type` are also supplied.
* With no profile loaded and an incomplete `CONTREE_TOKEN` / `--token`,
  the server stops with “No API token configured” rather than running
  with half-set credentials.

Token resolution order, per field:

```
token    --token   >  CONTREE_TOKEN   >  NEBIUS_API_KEY*   >  profile.token
project  --project >  CONTREE_PROJECT >  NEBIUS_AI_PROJECT* >  profile.project
url      --url     >  CONTREE_URL                          >  profile.url
                                                          >  IAM default (IAM only)
```

`*` `NEBIUS_*` are read only when both are set.

Tokens passed via env may appear in process listings — prefer the
profile file for routine use.

## Server Options

| Option             | Environment Variable      | Default                                                    | Description                                            |
| ------------------ | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| -                  | `CONTREE_HOME`            | `$XDG_CONFIG_HOME/contree` (typically `~/.config/contree`) | Directory containing `auth.ini` and MCP state          |
| `--profile`        | `CONTREE_PROFILE`         | active profile from `auth.ini`                             | Profile to use                                         |
| `--token`          | `CONTREE_TOKEN`           | from profile                                               | API token (overrides profile)                          |
| `--url`            | `CONTREE_URL`             | from profile                                               | API base URL (overrides profile)                       |
| `--project`        | `CONTREE_PROJECT`         | from profile                                               | Project ID for IAM auth                                |
| `--mode`           | -                         | `stdio`                                                    | `stdio` or `http`                                      |
| `--http-port`      | -                         | `9452`                                                     | HTTP mode port                                         |
| `--http-listen`    | -                         | `127.0.0.1`                                                | HTTP mode bind address                                 |
| `--log-level`      | -                         | `warning`                                                  | Logging level                                          |
| `--version` / `-V` | -                         | -                                                          | Print the User-Agent the server emits and exit         |
| -                  | `CONTREE_NO_UPDATE_CHECK` | unset                                                      | Disable the daily PyPI update check (set to any value) |

## Cache Configuration

| Option               | Default                                                                   |
| -------------------- | ------------------------------------------------------------------------- |
| `--cache-files`      | `$CONTREE_HOME/mcp/files.db` (typically `~/.config/contree/mcp/files.db`) |
| `--cache-general`    | `$CONTREE_HOME/mcp/cache.db` (typically `~/.config/contree/mcp/cache.db`) |
| `--cache-prune-days` | `60`                                                                      |

## Client Configuration Examples

With credentials stored in `~/.config/contree/auth.ini`, MCP client
configs are minimal:

### Claude Code

```bash theme={null}
claude mcp add --transport stdio contree -- $(which uvx) contree-mcp
```

### HTTP Mode

For network access from other machines:

```bash theme={null}
contree-mcp --mode http --http-port 9452 --http-listen 0.0.0.0
```

Visit `http://localhost:9452/` for interactive documentation with setup guides, tool reference, and best practices.

<Frame>
  <img alt="Contree MCP Server HTTP interface" />
</Frame>

## Manual Installation

```bash theme={null}
# Using uv
uv pip install contree-mcp

# Using pip
pip install contree-mcp

# Container environments (PEP 668)
pip install --break-system-packages contree-mcp
```


# Integration
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/integration/index



Setting up and configuring Contree MCP.

<Columns>
  <Card title="Configuration" href="./configuration" icon="sliders" />

  <Card title="Troubleshooting" href="./troubleshooting" icon="triangle-exclamation" />
</Columns>

## Quick Setup

See the [Quickstart](../quickstart) for basic setup instructions.

## Configuration Options

Credentials live in a profile-based `auth.ini` shared with
[`contree-cli`](https://docs.contree.dev/cli/tutorial/installation.html);
install the CLI and run `contree auth` once to populate it. The MCP
server then reads the active profile automatically.

| Option             | Environment Variable | Default                                                    |
| ------------------ | -------------------- | ---------------------------------------------------------- |
| -                  | `CONTREE_HOME`       | `$XDG_CONFIG_HOME/contree` (typically `~/.config/contree`) |
| `--profile`        | `CONTREE_PROFILE`    | active profile from `auth.ini`                             |
| `--token`          | `CONTREE_TOKEN`      | from profile                                               |
| `--url`            | `CONTREE_URL`        | from profile                                               |
| `--project`        | `CONTREE_PROJECT`    | from profile (IAM auth only)                               |
| `--mode`           | -                    | `stdio`                                                    |
| `--http-port`      | -                    | `9452`                                                     |
| `--log-level`      | -                    | `warning`                                                  |
| `--version` / `-V` | -                    | print User-Agent and exit                                  |

Resolution priority for credentials: \*\*CLI flag > environment variable

> stored profile\*\*.

## Supported Clients

* Claude Code
* Claude Desktop
* OpenAI Codex CLI
* Any MCP-compatible client

## See Also

* [Configuration](./configuration) - Detailed config options
* [Troubleshooting](./troubleshooting) - Common issues


# Troubleshooting
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/integration/troubleshooting



Common issues and solutions.

## Connection Issues

### “No API token configured” Error

**Cause**: No active profile in `auth.ini` and no `--token` /
`CONTREE_TOKEN` override.

**Solution (recommended):** install `contree-cli` and run `contree auth`:

```bash theme={null}
uv tool install contree-cli   # or: pip install contree-cli
contree auth                  # interactive setup
```

This writes `~/.config/contree/auth.ini`. The MCP server reads it
automatically.

For a one-off override:

```bash theme={null}
export CONTREE_TOKEN="your-token"
export CONTREE_URL="https://api.tokenfactory.nebius.com/sandboxes"
export CONTREE_PROJECT="your-nebius-project-id"   # only for IAM auth
```

### Server logs `Ignoring NEBIUS_API_KEY: NEBIUS_AI_PROJECT is not set`

**Cause**: Your shell has `NEBIUS_API_KEY` set (typically for the
Nebius SDK or terraform provider) but no `NEBIUS_AI_PROJECT`. The MCP
server treats this as an incomplete IAM credential and falls back to
the active profile from `auth.ini`. This is *not* an error — it’s a
deliberate guard against an ambient env var hijacking your saved
profile.

**Solution**: nothing to do if you wanted the profile to load. If you
*meant* to authenticate via env, also export `NEBIUS_AI_PROJECT` (or
use the MCP-specific `CONTREE_TOKEN` / `CONTREE_PROJECT`, which layer
per-field on top of the profile and don’t have this guard).

### “IAM auth requires a project ID” Error

**Cause**: The active profile (or the env/CLI overrides) is IAM-typed
but no project ID was supplied.

**Solution**: either add `project = ...` under the matching
`[profile:<name>]` section, set `CONTREE_PROJECT`, or pass
`--project <id>`. For legacy JWT deployments, set `type = jwt` in the
profile — projects aren’t needed there.

### “Connection refused” Error

**Cause**: Server not reachable or wrong URL.

**Solution**: Verify the URL in the active profile (or pass
`--url`/`CONTREE_URL`):

```bash theme={null}
export CONTREE_URL="https://api.tokenfactory.nebius.com/sandboxes"
```

### “Forbidden” / Missing Permissions

**Cause**: The active token doesn’t have the permission your call
needs (`spawn`, `import`, `set_image_tag`, `cancel`, …).

**Solution**: ask the `whoami` tool to enumerate what’s available:

```json theme={null}
{"tool": "whoami"}
```

If a permission is `false`, the only recourse is a token with
different grants — the MCP server cannot escalate.

## Tool Errors

### “Image not found”

**Cause**: Invalid image UUID or tag.

**Solutions**:

1. Check with `list_images`
2. Ensure the UUID is correct
3. For tags, use `tag:` prefix: `"image": "tag:python:3.11"`

### “Directory state not found”

**Cause**: Invalid `directory_state_id` or expired session.

**Solution**: Call `rsync` again to get a new `directory_state_id`.

### “Operation timed out”

**Cause**: Command exceeded timeout.

**Solution**: Increase the timeout:

```json theme={null}
{"tool": "run", "args": {
  "command": "...",
  "timeout": 600
}}
```

## Performance Issues

### Slow File Sync

**Cause**: Large files or too many files.

**Solutions**:

1. Use exclusions:

   ```json theme={null}
   {"exclude": ["node_modules", ".git", "__pycache__", "*.log"]}
   ```
2. Sync only what you need
3. Use glob patterns for specific files

### Commands Taking Long to Start

**Cause**: VM startup time (\~2-5 seconds).

**Solutions**:

1. Batch operations when possible
2. Use async for parallel operations
3. Reuse images with dependencies pre-installed

## Debugging

### Enable Debug Logging

Pass `--log-level debug` to the server:

```bash theme={null}
contree-mcp --log-level debug ...
```

In an MCP client config that spawns the server, append the flag to
`args`:

```json theme={null}
{
  "mcpServers": {
    "contree": {
      "command": "uvx",
      "args": ["contree-mcp", "--log-level", "debug"]
    }
  }
}
```

### Confirm the Installed Version

`contree-mcp --version` (or `-V`) prints the User-Agent the server
emits on every backend call. Useful when triaging which build is
actually wired into your client:

```bash theme={null}
$ contree-mcp --version
contree-mcp/0.1.1 Python/3.13.0.final.0 Linux-6.5.0-arm64
```

### Check Operation Status

For async operations:

```json theme={null}
{"tool": "get_operation", "args": {"operation_id": "op-..."}}
```

### View Image Lineage

To understand how an image was created:

```
contree://image/your-image-uuid/lineage
```

## Getting Help

* [GitHub Issues](https://github.com/nebius/contree/issues)
* Check the [Concepts](../concepts/index) for understanding
* See [Patterns](../patterns) for best practices


# Patterns
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/patterns



Common workflows and mistakes to avoid.

## Run Python Script with Local Files

```json theme={null}
// 1. Check for image
{"tool": "list_images", "args": {"tag_prefix": "python"}}

// 2. Import if needed
{"tool": "import_image", "args": {"registry_url": "docker://python:3.11-slim"}}

// 3. Sync files
{"tool": "rsync", "args": {
  "source": "/project", "destination": "/app",
  "exclude": ["__pycache__", ".git", ".venv"]
}}

// 4. Run
{"tool": "run", "args": {
  "command": "python /app/main.py",
  "image": "img-uuid",
  "directory_state_id": "ds-xxx"
}}
```

## Install Dependencies and Save

```json theme={null}
// Save changes with disposable=false
{"tool": "run", "args": {
  "command": "pip install numpy pandas",
  "image": "tag:python:3.11",
  "disposable": false
}}
// Returns: {"result_image": "img-with-deps"}

// Use new image for subsequent runs
{"tool": "run", "args": {
  "command": "python /app/train.py",
  "image": "img-with-deps",
  "directory_state_id": "ds-xxx"
}}
```

**Mistake**: Forgetting `disposable=false` means changes are discarded.

## Parallel Execution

```json theme={null}
// Launch async
{"tool": "run", "args": {"command": "python exp_a.py", "image": "img", "wait": false}}
{"tool": "run", "args": {"command": "python exp_b.py", "image": "img", "wait": false}}

// Wait for all
{"tool": "wait_operations", "args": {"operation_ids": ["op-1", "op-2"]}}
```

**Mistake**: Using `wait=false` for single operations adds unnecessary complexity.

## Build and Extract Artifact

```json theme={null}
// Build with disposable=false
{"tool": "run", "args": {
  "command": "cargo build --release",
  "image": "tag:rust:1.75",
  "directory_state_id": "ds-project",
  "disposable": false,
  "timeout": 300
}}

// Download result
{"tool": "download", "args": {
  "image": "img-built",
  "path": "/app/target/release/myapp",
  "destination": "./myapp",
  "executable": true
}}
```

## Rollback After Failure

```
// View lineage
contree://image/broken-uuid/lineage
// Returns: {"parent": {"image": "working-parent-uuid"}}

// Continue from working state
{"tool": "run", "args": {
  "command": "python fixed.py",
  "image": "working-parent-uuid"
}}
```

***

## Common Mistakes

### Re-syncing unchanged files

**Wrong**: Calling `rsync` before every `run`

**Right**: Sync once, reuse `directory_state_id` for all runs. Re-sync only when files change.

### Importing without checking

**Wrong**: `import_image` immediately

**Right**: `list_images` first to check if image exists

### Chaining commands in one string

**Wrong**:

```json theme={null}
{"command": "apt update && apt install python && pip install numpy && python train.py"}
```

**Right**: Run each step separately with `disposable=false`. Enables rollback if later steps fail.

### Using tags for one-off images

**Wrong**: Creating tags for temporary experiments

**Right**: Use UUIDs directly. Tags are for frequently-reused images.

### Not excluding build artifacts

**Wrong**: rsync without exclusions

**Right**: Always exclude `__pycache__`, `.git`, `.venv`, `node_modules`, `target`, `dist`

### Ignoring filesystem\_changed

When `filesystem_changed: false`, `result_image` equals input image - no new snapshot was created.


# build-project
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/build-project



Build a project: install dependencies and run tests.

## Description

The `build-project` prompt provides instructions for a standard build workflow: sync files, install dependencies, and run tests.

## Parameters

| Parameter     | Type   | Required | Default            | Description                     |
| ------------- | ------ | -------- | ------------------ | ------------------------------- |
| `source`      | string | Yes      | -                  | Local directory path to sync    |
| `install_cmd` | string | No       | `pip install -e .` | Dependency installation command |
| `test_cmd`    | string | No       | `pytest`           | Test execution command          |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "source": "/home/user/myproject",
  "install_cmd": "pip install -e '.[dev]'",
  "test_cmd": "pytest -v tests/"
}
```

Returns:

```markdown theme={null}
Build and test the project:

1. Sync `/home/user/myproject` to `/app` using `rsync`
2. Import `python:3.11-slim` if needed
3. Install dependencies with `pip install -e '.[dev]'` (use `disposable=false`)
4. Run tests with `pytest -v tests/` on the result image
5. Report test results
```

## Example Usage

### Standard Python Project

```json theme={null}
{
  "prompt": "build-project",
  "args": {
    "source": "/path/to/project"
  }
}
```

### With Custom Commands

```json theme={null}
{
  "prompt": "build-project",
  "args": {
    "source": "/path/to/project",
    "install_cmd": "pip install -r requirements.txt",
    "test_cmd": "python -m pytest --cov=src tests/"
  }
}
```

### Poetry Project

```json theme={null}
{
  "prompt": "build-project",
  "args": {
    "source": "/path/to/project",
    "install_cmd": "pip install poetry && poetry install",
    "test_cmd": "poetry run pytest"
  }
}
```

## Implementation Notes

The agent should:

1. Sync files with `rsync`:

   ```json theme={null}
   {
     "source": "<source_path>",
     "destination": "/app",
     "exclude": ["__pycache__", ".git", ".venv", "node_modules"]
   }
   ```
2. Check for Python image, import if needed
3. Install dependencies with `run`:

   ```json theme={null}
   {
     "command": "<install_cmd>",
     "image": "tag:python:3.11-slim",
     "directory_state_id": "<from_rsync>",
     "cwd": "/app",
     "disposable": false
   }
   ```
4. Run tests with `run`:

   ```json theme={null}
   {
     "command": "<test_cmd>",
     "image": "<result_image_from_install>",
     "directory_state_id": "<from_rsync>",
     "cwd": "/app"
   }
   ```
5. Report test results (exit code, stdout, stderr)

## See Also

* [multi-stage-build](./multi-stage-build) - Complex builds with checkpoints
* [sync-and-run](./sync-and-run) - Simple file sync and execution
* [install-packages](./install-packages) - Just install packages


# debug-failure
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/debug-failure



Diagnose a failed command and suggest fixes.

## Description

The `debug-failure` prompt provides a systematic approach to diagnosing and fixing failed container operations.

## Parameters

| Parameter      | Type   | Required | Default | Description           |
| -------------- | ------ | -------- | ------- | --------------------- |
| `operation_id` | string | Yes      | -       | Operation ID to debug |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "operation_id": "op-abc-123-def"
}
```

Returns:

```markdown theme={null}
Debug the failed operation `op-abc-123-def`:

1. Use `get_operation` to retrieve the operation result
2. Analyze:
   - `exit_code`: Non-zero indicates command failure
   - `stderr`: Contains error messages and stack traces
   - `stdout`: May contain partial output or clues
   - `timed_out`: If true, command exceeded timeout
3. Common issues to check:
   - Missing files (file not found errors)
   - Missing dependencies (import errors, command not found)
   - Permission issues (though commands run as root)
   - Timeout exceeded (increase timeout or optimize command)
4. Suggest specific fixes based on the error
5. If needed, re-run with fixes applied
```

## Example Usage

### Debug Build Failure

```json theme={null}
{
  "prompt": "debug-failure",
  "args": {
    "operation_id": "op-build-failed-123"
  }
}
```

### Debug Test Failure

```json theme={null}
{
  "prompt": "debug-failure",
  "args": {
    "operation_id": "op-test-run-456"
  }
}
```

## Common Error Patterns

### Missing Dependencies

**Symptom:** `ModuleNotFoundError` or `command not found`

**Solution:** Install missing packages with `install-packages` or use a prepared environment.

### File Not Found

**Symptom:** `No such file or directory`

**Solution:** Verify path with `list_files`, ensure files are synced with `rsync`.

### Timeout

**Symptom:** `timed_out: true`

**Solution:** Increase `timeout` parameter or break into smaller operations.

### Permission Denied

**Symptom:** `Permission denied`

**Solution:** Commands run as root, so check if file exists and is accessible.

## Implementation Notes

The agent should:

1. Retrieve operation with `get_operation`:

   ```json theme={null}
   {"operation_id": "<operation_id>"}
   ```
2. Analyze the result:

   * Check `exit_code` (0 = success, non-zero = failure)
   * Read `stderr` for error messages
   * Check `timed_out` flag
   * Review `stdout` for partial output
3. Diagnose based on error patterns:

   * Import errors → missing packages
   * File not found → path issues
   * Timeout → need more time or optimization
4. Suggest and implement fixes

## See Also

* [inspect-image](./inspect-image) - Explore image contents
* [Error Handling Guide](../resources) - Common errors and solutions
* [build-project](./build-project) - Retry build after fix


# Prompts Reference
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/index



MCP prompts for common Contree workflows. Prompts provide structured instructions that guide AI agents through multi-step tasks.

<Columns>
  <Card title="prepare-environment" href="./prepare-environment" icon="gear" />

  <Card title="run-python" href="./run-python" icon="terminal" />

  <Card title="run-shell" href="./run-shell" icon="terminal" />

  <Card title="sync-and-run" href="./sync-and-run" icon="rotate" />

  <Card title="install-packages" href="./install-packages" icon="box-open" />

  <Card title="parallel-tasks" href="./parallel-tasks" icon="code-fork" />

  <Card title="build-project" href="./build-project" icon="hammer" />

  <Card title="debug-failure" href="./debug-failure" icon="bug" />

  <Card title="inspect-image" href="./inspect-image" icon="magnifying-glass" />

  <Card title="multi-stage-build" href="./multi-stage-build" icon="layer-group" />
</Columns>

## Quick Reference

| Prompt                                       | Description                                                   | Key Parameters                                   |
| -------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------ |
| [prepare-environment](./prepare-environment) | Prepare container environment with CHECK-PREPARE-EXECUTE flow | `task`, `base`, `project`, `packages`            |
| [run-python](./run-python)                   | Run Python code in isolated container                         | `code`                                           |
| [run-shell](./run-shell)                     | Run shell command in isolated container                       | `command`, `image`                               |
| [sync-and-run](./sync-and-run)               | Sync local files and run command                              | `source`, `command`, `image`                     |
| [install-packages](./install-packages)       | Install packages and create reusable image                    | `packages`, `image`                              |
| [parallel-tasks](./parallel-tasks)           | Run multiple tasks in parallel                                | `tasks`, `image`                                 |
| [build-project](./build-project)             | Build project: install deps and run tests                     | `source`, `install_cmd`, `test_cmd`              |
| [debug-failure](./debug-failure)             | Diagnose failed operation                                     | `operation_id`                                   |
| [inspect-image](./inspect-image)             | Explore container image contents                              | `image`                                          |
| [multi-stage-build](./multi-stage-build)     | Multi-stage build with rollback points                        | `source`, `install_cmd`, `build_cmd`, `test_cmd` |

## Using Prompts

### With MCP Clients

MCP-compatible clients can invoke prompts directly:

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

### Prompt Output

Prompts return structured instructions that guide the agent through:

1. **Step-by-step workflows** - Ordered operations with clear dependencies
2. **Tool selection** - Which Contree tools to use and when
3. **Parameter guidance** - Correct values for each tool call
4. **Best practices** - Following the CHECK-PREPARE-EXECUTE pattern

## Categories

### Environment Setup

* [prepare-environment](./prepare-environment) - Full workflow with environment reuse
* [install-packages](./install-packages) - Install and tag for reuse

### Code Execution

* [run-python](./run-python) - Quick Python execution
* [run-shell](./run-shell) - Shell command execution
* [sync-and-run](./sync-and-run) - Local files + execution

### Building and Testing

* [build-project](./build-project) - Standard build + test workflow
* [multi-stage-build](./multi-stage-build) - Complex builds with checkpoints

### Operations

* [parallel-tasks](./parallel-tasks) - Concurrent execution
* [debug-failure](./debug-failure) - Error diagnosis
* [inspect-image](./inspect-image) - Image exploration


# inspect-image
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/inspect-image



Explore the contents of a container image.

## Description

The `inspect-image` prompt provides instructions for thoroughly examining a container image to understand its contents, installed software, and configuration.

## Parameters

| Parameter | Type   | Required | Default | Description                  |
| --------- | ------ | -------- | ------- | ---------------------------- |
| `image`   | string | Yes      | -       | Image UUID or tag to inspect |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "image": "tag:python:3.11-slim"
}
```

Returns:

```markdown theme={null}
Inspect the container image `tag:python:3.11-slim`:

1. Use `run` with the image to explore:
   - `ls -la /` - List root directory contents
   - `cat /etc/os-release` - Check OS version
   - `which python pip node` - Find installed tools
   - `pip list` or `dpkg -l` - List installed packages
2. Report findings:
   - Operating system and version
   - Available languages/runtimes
   - Key installed packages
   - Notable files or directories
3. Use `disposable=true` (default) since we're just exploring
```

## Example Usage

### Explore Python Image

```json theme={null}
{
  "prompt": "inspect-image",
  "args": {
    "image": "tag:python:3.11-slim"
  }
}
```

### Explore Custom Image

```json theme={null}
{
  "prompt": "inspect-image",
  "args": {
    "image": "abc123-def456-uuid"
  }
}
```

### Explore Alpine

```json theme={null}
{
  "prompt": "inspect-image",
  "args": {
    "image": "tag:alpine:latest"
  }
}
```

## Implementation Notes

The agent should use the free inspection tools first, then `run` for dynamic queries:

1. **Use `list_files` first** (free, no VM):

   ```json theme={null}
   {"image": "<image>", "path": "/"}
   {"image": "<image>", "path": "/etc"}
   {"image": "<image>", "path": "/usr/local/bin"}
   ```
2. **Use `read_file` for config files** (free, no VM):

   ```json theme={null}
   {"image": "<image>", "path": "/etc/os-release"}
   ```
3. **Use `run` for dynamic queries** (spawns VM):

   ```json theme={null}
   {"command": "pip list", "image": "<image>"}
   {"command": "which python pip node", "image": "<image>"}
   ```
4. Report findings in a structured format:

   * OS: Debian 12 / Alpine 3.18 / etc.
   * Languages: Python 3.11, Node.js 20, etc.
   * Key packages: numpy, flask, etc.
   * Notable directories: /app, /data, etc.

## See Also

* [list\_files](../tools/list_files) - List directory contents (free)
* [read\_file](../tools/read_file) - Read file contents (free)
* [debug-failure](./debug-failure) - Debug after inspection


# install-packages
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/install-packages



Install packages and create a reusable image.

## Description

The `install-packages` prompt provides instructions for installing packages in a container and tagging the result for future reuse. It follows the prepare-and-tag pattern.

## Parameters

| Parameter  | Type   | Required | Default            | Description                           |
| ---------- | ------ | -------- | ------------------ | ------------------------------------- |
| `packages` | string | Yes      | -                  | Packages to install (space-separated) |
| `image`    | string | No       | `python:3.11-slim` | Base image to use                     |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "packages": "flask gunicorn",
  "image": "python:3.11-slim"
}
```

Returns:

```markdown theme={null}
Install packages in a container:

1. Check if base image `tag:python:3.11-slim` exists with `list_images`
2. If not, import it with `import_image`
3. Run `pip install flask gunicorn` with `disposable=false` to save the image
4. Tag the result for reuse (e.g., `claude/common/python/custom-deps:3.11`)

The returned `result_image` can be used for subsequent commands.
```

## Example Usage

### Python Packages

```json theme={null}
{
  "prompt": "install-packages",
  "args": {
    "packages": "numpy pandas matplotlib scikit-learn"
  }
}
```

### Web Framework Stack

```json theme={null}
{
  "prompt": "install-packages",
  "args": {
    "packages": "fastapi uvicorn sqlalchemy alembic"
  }
}
```

### System Packages

For system packages, use a different base image and package manager:

```json theme={null}
{
  "prompt": "install-packages",
  "args": {
    "packages": "curl wget git",
    "image": "ubuntu:22.04"
  }
}
```

Note: For Ubuntu, the agent should adapt to use `apt install` instead of `pip install`.

## Implementation Notes

The agent should:

1. Check if base image exists with `list_images`
2. Import if needed with `import_image`
3. Install packages with `run`:

   ```json theme={null}
   {
     "command": "pip install <packages>",
     "image": "tag:<base_image>",
     "disposable": false
   }
   ```
4. Tag the result with `set_tag`:

   ```json theme={null}
   {
     "image_uuid": "<result_image>",
     "tag": "common/<purpose>/<base_image>"
   }
   ```

## See Also

* [prepare-environment](./prepare-environment) - Full environment preparation
* [build-project](./build-project) - Build with dependencies
* [multi-stage-build](./multi-stage-build) - Complex multi-stage builds


# multi-stage-build
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/multi-stage-build



Multi-stage build with rollback points.

## Description

The `multi-stage-build` prompt provides instructions for complex builds with multiple stages, each creating a checkpoint for potential rollback.

## Parameters

| Parameter     | Type   | Required | Default            | Description                     |
| ------------- | ------ | -------- | ------------------ | ------------------------------- |
| `source`      | string | Yes      | -                  | Local directory path to sync    |
| `install_cmd` | string | No       | `pip install -e .` | Dependency installation command |
| `build_cmd`   | string | No       | `python -m build`  | Build command                   |
| `test_cmd`    | string | No       | `pytest`           | Test command                    |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "source": "/home/user/project",
  "install_cmd": "pip install -e '.[dev]'",
  "build_cmd": "python -m build",
  "test_cmd": "pytest -v"
}
```

Returns:

```markdown theme={null}
Execute a multi-stage build with rollback checkpoints:

Source: `/home/user/project`

**Stage 1: Setup Base**
1. Check if `tag:python:3.11-slim` exists, import if needed
2. Sync source files with `rsync`

**Stage 2: Install Dependencies** (checkpoint: `deps-installed`)
1. Run `pip install -e '.[dev]'` with `disposable=false`
2. Save `result_image` as rollback point
3. If this fails, report error and stop

**Stage 3: Build** (checkpoint: `build-complete`)
1. Run `python -m build` on deps image with `disposable=false`
2. Save `result_image` as rollback point
3. If this fails, can rollback to deps-installed image

**Stage 4: Test**
1. Run `pytest -v` on build image (disposable=true for tests)
2. Report test results
3. If tests fail, can rollback to build-complete or deps-installed

**Rollback Strategy:**
- Keep track of each stage's `result_image` UUID
- On failure, report which checkpoint to resume from
- Previous checkpoints remain valid for retry
```

## Example Usage

### Python Package Build

```json theme={null}
{
  "prompt": "multi-stage-build",
  "args": {
    "source": "/path/to/package"
  }
}
```

### Custom Build Pipeline

```json theme={null}
{
  "prompt": "multi-stage-build",
  "args": {
    "source": "/path/to/project",
    "install_cmd": "pip install poetry && poetry install",
    "build_cmd": "poetry build",
    "test_cmd": "poetry run pytest --cov"
  }
}
```

### Rust Project

```json theme={null}
{
  "prompt": "multi-stage-build",
  "args": {
    "source": "/path/to/rust-project",
    "install_cmd": "cargo fetch",
    "build_cmd": "cargo build --release",
    "test_cmd": "cargo test"
  }
}
```

## Stage Details

### Stage 1: Setup Base

* Ensures base image exists
* Syncs source files
* No checkpoint needed (base image is the checkpoint)

### Stage 2: Install Dependencies

* Runs install command with `disposable=false`
* Saves result as `deps-installed` checkpoint
* **Rollback target:** If install fails, fix and retry from base

### Stage 3: Build

* Runs build command with `disposable=false`
* Saves result as `build-complete` checkpoint
* **Rollback target:** If build fails, can retry from `deps-installed`

### Stage 4: Test

* Runs tests with `disposable=true` (no need to save test artifacts)
* Reports results
* **Rollback targets:** Can retry from `build-complete` or `deps-installed`

## Implementation Notes

The agent should track checkpoints:

```
base_image = "tag:python:3.11-slim"
      |
      v
deps_image = run(install_cmd, disposable=false).result_image
      |
      v
build_image = run(build_cmd, image=deps_image, disposable=false).result_image
      |
      v
test_result = run(test_cmd, image=build_image, disposable=true)
```

On failure at any stage, report:

* Which stage failed
* Available rollback points
* How to resume

## See Also

* [build-project](./build-project) - Simpler build workflow
* [debug-failure](./debug-failure) - Debug build failures
* [State Management Guide](../resources) - Rollback patterns


# parallel-tasks
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/parallel-tasks



Run multiple tasks in parallel.

## Description

The `parallel-tasks` prompt provides instructions for executing multiple independent tasks concurrently using Contree’s async execution capabilities.

## Parameters

| Parameter | Type   | Required | Default            | Description                 |
| --------- | ------ | -------- | ------------------ | --------------------------- |
| `tasks`   | string | Yes      | -                  | Tasks to run (one per line) |
| `image`   | string | No       | `python:3.11-slim` | Base image to use           |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "tasks": "python test_unit.py\npython test_integration.py\npython test_e2e.py",
  "image": "python:3.11-slim"
}
```

Returns:

```markdown theme={null}
Run these tasks in parallel:

Tasks (one per line):
python test_unit.py
python test_integration.py
python test_e2e.py

Steps:
1. Ensure image `tag:python:3.11-slim` exists (import if needed)
2. Call `run` for each task with `wait=false` - make parallel tool calls
3. Collect all `operation_id` values
4. Use `wait_operations` to wait for all to complete
5. Report results from each task
```

## Example Usage

### Parallel Tests

```json theme={null}
{
  "prompt": "parallel-tasks",
  "args": {
    "tasks": "pytest tests/unit/\npytest tests/integration/\npytest tests/e2e/"
  }
}
```

### Multiple Experiments

```json theme={null}
{
  "prompt": "parallel-tasks",
  "args": {
    "tasks": "python train.py --lr 0.001\npython train.py --lr 0.01\npython train.py --lr 0.1"
  }
}
```

### Build Multiple Targets

```json theme={null}
{
  "prompt": "parallel-tasks",
  "args": {
    "tasks": "cargo build --target x86_64-unknown-linux-gnu\ncargo build --target aarch64-unknown-linux-gnu",
    "image": "rust:1.75"
  }
}
```

## Implementation Notes

The agent should:

1. Ensure the image exists (check with `list_images`, import if needed)
2. Launch all tasks in parallel with `wait=false`:

   ```json theme={null}
   // Make these calls in parallel
   {"command": "python test_unit.py", "image": "tag:python:3.11-slim", "wait": false}
   {"command": "python test_integration.py", "image": "tag:python:3.11-slim", "wait": false}
   {"command": "python test_e2e.py", "image": "tag:python:3.11-slim", "wait": false}
   ```
3. Collect the returned `operation_id` values
4. Wait for all with `wait_operations`:

   ```json theme={null}
   {"operation_ids": ["op-1", "op-2", "op-3"]}
   ```
5. Process and report results from each operation

## See Also

* [build-project](./build-project) - Sequential build workflow
* [debug-failure](./debug-failure) - Debug failed operations
* [Async Guide](../resources) - Async execution patterns


# prepare-environment
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/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


# run-python
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/run-python



Run Python code in an isolated container.

## Description

The `run-python` prompt provides a simple way to execute Python code in a container. It handles image selection and provides clear instructions for the execution.

## Parameters

| Parameter | Type   | Required | Default | Description            |
| --------- | ------ | -------- | ------- | ---------------------- |
| `code`    | string | Yes      | -       | Python code to execute |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "code": "import sys\nprint(f'Python {sys.version}')"
}
```

Returns:

````markdown theme={null}
Run this Python code in a container:

```python
import sys
print(f'Python {sys.version}')
````

Use `run` with `tag:python:3.11-slim` image. If the image doesn’t exist, import it first.

````

## Example Usage

### Simple Calculation

```json
{
  "prompt": "run-python",
  "args": {
    "code": "print(sum(range(100)))"
  }
}
````

### Multi-line Script

```json theme={null}
{
  "prompt": "run-python",
  "args": {
    "code": "def factorial(n):\n    return 1 if n <= 1 else n * factorial(n-1)\n\nfor i in range(10):\n    print(f'{i}! = {factorial(i)}')"
  }
}
```

### With Package Usage

```json theme={null}
{
  "prompt": "run-python",
  "args": {
    "code": "import numpy as np\nprint(np.random.rand(5))"
  }
}
```

Note: If the code requires packages not in the base image, you’ll need to install them first using `install-packages` or `prepare-environment`.

## Implementation Notes

The agent should:

1. Check if `tag:python:3.11-slim` exists with `list_images`
2. If not found, import it with `import_image`
3. Execute the code with `run`:

   ```json theme={null}
   {
     "command": "python -c '<escaped_code>'",
     "image": "tag:python:3.11-slim"
   }
   ```

## See Also

* [run-shell](./run-shell) - Run shell commands
* [sync-and-run](./sync-and-run) - Run with local files
* [install-packages](./install-packages) - Install dependencies first


# run-shell
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/run-shell



Run a shell command in an isolated container.

## Description

The `run-shell` prompt provides a simple way to execute shell commands in a container with a specified base image.

## Parameters

| Parameter | Type   | Required | Default        | Description              |
| --------- | ------ | -------- | -------------- | ------------------------ |
| `command` | string | Yes      | -              | Shell command to execute |
| `image`   | string | No       | `ubuntu:22.04` | Base image to use        |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "command": "uname -a && cat /etc/os-release",
  "image": "alpine:latest"
}
```

Returns:

````markdown theme={null}
Run this command in a container:

```bash
uname -a && cat /etc/os-release
````

Use image `tag:alpine:latest`. If the image doesn’t exist, import it first with `import_image`.

````

## Example Usage

### Basic Command

```json
{
  "prompt": "run-shell",
  "args": {
    "command": "ls -la /etc"
  }
}
````

### With Specific Image

```json theme={null}
{
  "prompt": "run-shell",
  "args": {
    "command": "go version",
    "image": "golang:1.21"
  }
}
```

### System Information

```json theme={null}
{
  "prompt": "run-shell",
  "args": {
    "command": "df -h && free -m && nproc"
  }
}
```

## Implementation Notes

The agent should:

1. Check if the specified image exists with `list_images`
2. If not found, import it with `import_image`
3. Execute the command with `run`:

   ```json theme={null}
   {
     "command": "<shell_command>",
     "image": "tag:<image>"
   }
   ```

## See Also

* [run-python](./run-python) - Run Python code
* [sync-and-run](./sync-and-run) - Run with local files
* [inspect-image](./inspect-image) - Explore image contents


# sync-and-run
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/prompts/sync-and-run



Sync local files to container and run a command.

## Description

The `sync-and-run` prompt provides instructions for syncing local project files to a container and executing a command. It handles the rsync workflow with proper exclusions.

## Parameters

| Parameter | Type   | Required | Default            | Description                  |
| --------- | ------ | -------- | ------------------ | ---------------------------- |
| `source`  | string | Yes      | -                  | Local directory path to sync |
| `command` | string | Yes      | -                  | Command to run after syncing |
| `image`   | string | No       | `python:3.11-slim` | Base image to use            |

## Generated Instructions

When invoked with:

```json theme={null}
{
  "source": "/home/user/myproject",
  "command": "python main.py",
  "image": "python:3.11-slim"
}
```

Returns:

```markdown theme={null}
Sync files and run command:

1. Use `rsync` to sync `/home/user/myproject` to `/app` in the container
   - Exclude: `__pycache__`, `.git`, `node_modules`, `.venv`
2. Use `run` with the returned `directory_state_id`
   - Image: `tag:python:3.11-slim` (import if needed)
   - Command: `python main.py`
   - Working directory: `/app`
```

## Example Usage

### Python Project

```json theme={null}
{
  "prompt": "sync-and-run",
  "args": {
    "source": "/path/to/project",
    "command": "pytest tests/"
  }
}
```

### Node.js Project

```json theme={null}
{
  "prompt": "sync-and-run",
  "args": {
    "source": "/path/to/webapp",
    "command": "npm test",
    "image": "node:20-slim"
  }
}
```

### Build and Run

```json theme={null}
{
  "prompt": "sync-and-run",
  "args": {
    "source": "/path/to/rust-project",
    "command": "cargo build --release && ./target/release/myapp",
    "image": "rust:1.75"
  }
}
```

## Implementation Notes

The agent should:

1. Use `rsync` to sync files:

   ```json theme={null}
   {
     "source": "<source_path>",
     "destination": "/app",
     "exclude": ["__pycache__", ".git", "node_modules", ".venv"]
   }
   ```
2. Check if the image exists, import if needed
3. Execute with `run`:

   ```json theme={null}
   {
     "command": "<command>",
     "image": "tag:<image>",
     "directory_state_id": "<from_rsync>",
     "cwd": "/app"
   }
   ```

## See Also

* [build-project](./build-project) - Full build workflow
* [run-python](./run-python) - Simple Python execution
* [run-shell](./run-shell) - Simple shell execution


# Quickstart
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/quickstart



Run your first container in 5 minutes.

## Prerequisites

* An MCP-compatible client (Claude Code, Claude Desktop, or OpenAI Codex CLI)
* A Contree API token

### Getting an API Token

Contree is in **Early Access**. To get an API token, fill out the request form at [contree.dev](https://contree.dev).

## Installation

### Step 1: Authenticate

`contree-mcp` reads the same `auth.ini` that
[`contree-cli`](https://docs.contree.dev/cli/tutorial/installation.html)
writes, so a single login covers both tools.

**Recommended:** install `contree-cli` and run `contree auth`:

```bash theme={null}
uv tool install contree-cli   # or: pip install contree-cli
contree auth                  # interactive setup
```

This writes `~/.config/contree/auth.ini` (mode `0600`). The MCP server
picks it up automatically.

If you prefer to write the file by hand:

```ini theme={null}
[DEFAULT]
profile = default

[profile:default]
type = iam
url = https://api.tokenfactory.nebius.com/sandboxes
token = <TOKEN HERE>
project = <NEBIUS PROJECT ID>
```

For the legacy JWT flow (`contree.dev`), use:

```ini theme={null}
[profile:default]
type = jwt
url = https://contree.dev
token = <TOKEN HERE>
```

To switch between profiles later: `contree auth switch <name>`, or
pass `--profile <name>` / `CONTREE_PROFILE=<name>` to `contree-mcp`.

### Step 2: Configure Your MCP Client

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport stdio contree -- $(which uvx) contree-mcp
    ```

    Restart Claude Code or run `/mcp` to verify.
  </Tab>

  <Tab title="Claude Desktop">
    Add to config file:

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "contree": {
          "command": "uvx",
          "args": ["contree-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="OpenAI Codex CLI">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.contree]
    command = "uvx"
    args = ["contree-mcp"]
    ```
  </Tab>
</Tabs>

<Note>
  You can also pass credentials via environment variables (`CONTREE_TOKEN`,
  `CONTREE_URL`, `CONTREE_PROJECT`, `CONTREE_PROFILE`) or CLI flags
  (`--token`, `--url`, `--project`, `--profile`). These are useful for
  ephemeral overrides — but tokens passed via env may show up in process
  listings, so for routine use prefer the `auth.ini` profile written by
  `contree auth`.
</Note>

## Your First Container

### Step 1: Check Available Images

```json theme={null}
{"tool": "list_images", "args": {"tag_prefix": "python", "limit": 5}}
```

If you don’t have any Python images, import one:

```json theme={null}
{"tool": "import_image", "args": {"registry_url": "docker://python:3.11-slim"}}
```

Response:

```json theme={null}
{
  "result_image": "abc123-def456-...",
  "state": "SUCCESS"
}
```

### Step 2: Run a Command

```json theme={null}
{
  "tool": "run",
  "args": {
    "command": "python -c \"print('Hello from Contree!')\"",
    "image": "abc123-def456-..."
  }
}
```

Response:

```json theme={null}
{
  "exit_code": 0,
  "stdout": "Hello from Contree!\n",
  "state": "SUCCESS"
}
```

### Step 3: Run with Local Files

First, sync your files:

```json theme={null}
{
  "tool": "rsync",
  "args": {
    "source": "/path/to/your/project",
    "destination": "/app",
    "exclude": ["__pycache__", ".git", ".venv"]
  }
}
```

Response:

```json theme={null}
{
  "directory_state_id": "ds_xyz789...",
  "stats": {"uploaded": 5, "cached": 10}
}
```

Then run with the synced files:

```json theme={null}
{
  "tool": "run",
  "args": {
    "command": "python /app/main.py",
    "image": "abc123-def456-...",
    "directory_state_id": "ds_xyz789..."
  }
}
```

## What’s Next?

<Columns>
  <Card title="Concepts" href="./concepts/index" icon="lightbulb">
    Understand images, lineage, and async execution.
  </Card>

  <Card title="Patterns" href="./patterns" icon="shapes">
    Common workflows and best practices.
  </Card>

  <Card title="Tool Reference" href="./tools/index" icon="screwdriver-wrench">
    Detailed parameters for all 15 tools.
  </Card>

  <Card title="Resources" href="./resources" icon="database">
    MCP resources and guide sections.
  </Card>
</Columns>


# Glossary
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/reference/glossary



Terms and definitions used in Contree MCP.

## A

* **Async Execution** — Running operations without waiting for completion. Use `wait=false` and poll with `get_operation` or `wait_operations`.

## D

* **Directory State** — A snapshot of local files synced with `rsync`. Identified by `directory_state_id`.
* **Disposable** — When `disposable=true` (default), filesystem changes are discarded after command execution.

## I

* **Image** — An immutable filesystem snapshot. Identified by UUID.
* **Image Lineage** — The parent-child relationships between images. View with `contree://image/{uuid}/lineage`.

## M

* **MCP (Model Context Protocol)** — The protocol used for AI agent tool communication.
* **MicroVM** — A lightweight virtual machine used for isolated command execution.

## O

* **Operation** — A running or completed task (command execution or image import). Identified by `operation_id`.

## R

* **Result Image** — The image UUID returned when running with `disposable=false` and filesystem changes occur.
* **Root Image** — An image imported from a container registry, with no parent.

## T

* **Tag** — A human-readable name for an image (e.g., `python:3.11`). Tags can point to different UUIDs over time.

## U

* **UUID** — Universally Unique Identifier. The primary way to reference images and operations.


# Reference
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/reference/index



Additional reference materials.

<Columns>
  <Card title="Glossary" href="./glossary" icon="book-bookmark" />
</Columns>

## Quick Links

* [Glossary](./glossary) - Terms and definitions


# Resources
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/resources



MCP resource templates for reading files and metadata. No VM needed.

## image\_file

Read a file from a container image.

**URI**: `contree://image/{image}/read/{path}`

| Parameter | Description                          |
| --------- | ------------------------------------ |
| `image`   | Image UUID or `tag:name`             |
| `path`    | Path inside image (no leading slash) |

**Examples:**

```
contree://image/abc123-uuid/read/etc/passwd
contree://image/tag:alpine:latest/read/etc/os-release
contree://image/tag:python:3.11/read/usr/local/lib/python3.11/site-packages/pip/__init__.py
```

**Returns:** Text content or base64-encoded binary.

***

## image\_ls

List directory contents in a container image.

**URI**: `contree://image/{image}/ls/{path}`

| Parameter | Description                   |
| --------- | ----------------------------- |
| `image`   | Image UUID or `tag:name`      |
| `path`    | Directory path (`.` for root) |

**Examples:**

```
contree://image/abc123-uuid/ls/.
contree://image/tag:python:3.11/ls/usr/local/lib
```

**Returns:** JSON with file listing (path, size, mode, is\_dir, mtime).

***

## image\_lineage

View image parent-child relationships and history.

**URI**: `contree://image/{image}/lineage`

| Parameter | Description |
| --------- | ----------- |
| `image`   | Image UUID  |

**Example:**

```
contree://image/abc123-uuid/lineage
```

**Returns:**

```json theme={null}
{
  "image": "abc123",
  "parent": {"image": "parent-uuid", "command": "pip install numpy"},
  "children": [],
  "ancestors": [],
  "root": {"image": "root-uuid", "registry_url": "docker://alpine:latest"},
  "depth": 2
}
```

**Use for:** Rollback (use any ancestor UUID), understanding history.

***

## guide

Agent guides and best practices.

**URI**: `contree://guide/{section}`

| Section      | Description                                   |
| ------------ | --------------------------------------------- |
| `workflow`   | Complete workflow patterns with decision tree |
| `reference`  | Tool reference and quick lookup               |
| `quickstart` | Common workflows and best practices           |
| `state`      | Image state, rollback, disposable mode        |
| `async`      | Parallel execution patterns                   |
| `tagging`    | Agent tagging conventions                     |
| `errors`     | Error handling and debugging                  |

**Examples:**

```
contree://guide/workflow
contree://guide/quickstart
contree://guide/async
contree://guide/errors
```

***

## instance\_operation

Read instance (command execution) operation details from cache.

**URI**: `contree://operations/instance/{operation_id}`

| Parameter      | Description                                 |
| -------------- | ------------------------------------------- |
| `operation_id` | Operation UUID from `run` with `wait=false` |

**Example:**

```
contree://operations/instance/op-abc-123-def
```

**Returns:**

```json theme={null}
{
  "state": "SUCCESS",
  "exit_code": 0,
  "stdout": "Hello, World!",
  "stderr": "",
  "result_image": "uuid-of-result",
  "resources": {"cpu_time_ms": 150, "memory_mb": 64}
}
```

**Use for:** Retrieving cached results of completed command executions.

***

## import\_operation

Read image import operation details from cache.

**URI**: `contree://operations/import/{operation_id}`

| Parameter      | Description                                          |
| -------------- | ---------------------------------------------------- |
| `operation_id` | Operation UUID from `import_image` with `wait=false` |

**Example:**

```
contree://operations/import/op-xyz-789-abc
```

**Returns:**

```json theme={null}
{
  "state": "SUCCESS",
  "registry_url": "docker://python:3.11-slim",
  "result_image": "uuid-of-imported-image",
  "result_tag": "python:3.11-slim"
}
```

**Use for:** Retrieving cached results of completed image imports.


# Reporting Security Issues
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/security



The Nebius team take security bugs seriously. We appreciate your efforts to responsibly disclose your findings, and
will make every effort to acknowledge your contributions.

To report a security issue, please use the GitHub Security Advisory
[“Report a Vulnerability”](https://github.com/nebius/contree-mcp/security/advisories/new) tab.

The Nebius team will send a response indicating the next steps in handling your report. After the initial reply to your
report, the Nebius team will keep you informed of the progress towards a fix and full announcement, and may ask for
additional information or guidance.

## Learning More About Security in Nebius

To learn more about security in Nebius, please see [this page](https://nebius.ai/docs/security).


# cancel_operation
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/cancel_operation



Cancel a running operation.

## TL;DR

* **Use when**: Operation taking too long, no longer needed
* **Returns**: Cancellation status
* **Cost**: No VM needed

## Parameters

| Parameter      | Type   | Required | Default | Description              |
| -------------- | ------ | -------- | ------- | ------------------------ |
| `operation_id` | string | Yes      | -       | Operation UUID to cancel |

## Response

```json theme={null}
{
  "success": true,
  "operation_id": "op-abc123"
}
```

## Examples

### Cancel Operation

```json theme={null}
{"tool": "cancel_operation", "args": {
  "operation_id": "op-abc123"
}}
```

## See Also

* [get\_operation](./get_operation) - Check operation status
* [list\_operations](./list_operations) - Find operations


# download
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/download



Download a file from a container image to local filesystem.

## TL;DR

* **Use when**: Extracting build artifacts, logs, binaries
* **Returns**: Success status, file size, path
* **Cost**: No VM needed

## Parameters

| Parameter     | Type    | Required | Default | Description                                                                                                                                           |
| ------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`       | string  | Yes      | -       | Image UUID or `tag:name`                                                                                                                              |
| `path`        | string  | Yes      | -       | Path inside container                                                                                                                                 |
| `destination` | string  | Yes      | -       | Absolute path on MCP host filesystem (`~` supported, parent dirs auto-created). This writes to the MCP server’s filesystem, not inside the container. |
| `executable`  | boolean | No       | `false` | Make file executable                                                                                                                                  |

## Response

```json theme={null}
{
  "success": true,
  "size": 12345,
  "size_human": "12.1 KB",
  "destination": "/local/path/binary",
  "source": {
    "image": "img-build-result",
    "path": "/app/dist/binary"
  },
  "executable": true
}
```

## Examples

### Download Build Artifact

```json theme={null}
{"tool": "download", "args": {
  "image": "img-build-result",
  "path": "/app/dist/binary",
  "destination": "~/downloads/binary",
  "executable": true
}}
```

### Download Log File

```json theme={null}
{"tool": "download", "args": {
  "image": "img-uuid",
  "path": "/var/log/app.log",
  "destination": "~/downloads/debug.log"
}}
```

> **Note:** `destination` must be an absolute path on the MCP server’s host filesystem (not inside the container). Use `~` for home directory. Parent directories are created automatically.

## See Also

* [upload](./upload) - Upload files to Contree
* [rsync](./rsync) - Sync directories


# get_guide
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/get_guide



Get agent guide sections for Contree best practices.

## Overview

`get_guide` provides access to documentation and best practices for using Contree. This tool is an alternative to the `contree://guide/{section}` resource for agents that don’t support MCP resources.

## Parameters

| Parameter | Type   | Required | Default | Description        |
| --------- | ------ | -------- | ------- | ------------------ |
| `section` | string | Yes      | -       | Guide section name |

### Available Sections

| Section      | Description                                   |
| ------------ | --------------------------------------------- |
| `workflow`   | Complete workflow patterns with decision tree |
| `reference`  | Tool reference with parameters and data flow  |
| `quickstart` | Quick examples for common operations          |
| `state`      | State management and rollback patterns        |
| `async`      | Parallel execution patterns                   |
| `tagging`    | Agent tagging conventions                     |
| `errors`     | Error handling and debugging                  |

## Returns

| Field                | Type   | Description                         |
| -------------------- | ------ | ----------------------------------- |
| `section`            | string | Requested section name              |
| `content`            | string | Guide content in Markdown           |
| `available_sections` | array  | List of all available section names |

## Cost

**Free** - No VM spawned. Returns static documentation.

## Examples

### Get Workflow Guide

```json theme={null}
{
  "tool": "get_guide",
  "args": {
    "section": "workflow"
  }
}
```

Response:

```json theme={null}
{
  "section": "workflow",
  "content": "# Contree Workflow Guide\n\n## Decision Tree: Which Image to Use?\n...",
  "available_sections": ["async", "errors", "quickstart", "reference", "state", "tagging", "workflow"]
}
```

### Get Error Handling Guide

```json theme={null}
{
  "tool": "get_guide",
  "args": {
    "section": "errors"
  }
}
```

### Get Tagging Convention

```json theme={null}
{
  "tool": "get_guide",
  "args": {
    "section": "tagging"
  }
}
```

## When to Use

Use `get_guide` when:

* Your agent runtime doesn’t support MCP resources
* You need documentation about Contree best practices
* You want to understand workflow patterns or error handling

If your agent supports MCP resources, prefer using the resource URI:

```
contree://guide/workflow
contree://guide/errors
```

## Guide Content Overview

### workflow

Decision trees for choosing images, complete examples for Python ML environments, anti-patterns to avoid, and project-specific environment guidance.

### reference

Quick reference table of all tools with parameters, returns, and costs. Detailed parameter documentation for key tools.

### quickstart

Basic command execution, file sync patterns, dependency chains, and best practices for UUIDs vs tags.

### state

Understanding immutable snapshots, disposable mode, rollback model with branching, and response fields.

### async

Sequential vs parallel patterns, launching multiple async operations, waiting for results, and operation states.

### tagging

Tag format convention `{scope}/{purpose}/{base}:{tag}`, when to tag as common vs project-specific, and common tags to search for.

### errors

Common error patterns (command failures, timeouts, missing images), solutions, and debugging workflow.

## See Also

* [Resources](../resources) - `contree://guide/{section}` resource alternative
* [list\_images](./list_images) - Find existing tagged images
* [set\_tag](./set_tag) - Tag images for reuse


# get_image
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/get_image



Get image details by UUID or tag.

## TL;DR

* **Use when**: Verifying an image exists, resolving tag to UUID
* **Returns**: Image UUID, tag, creation time
* **Cost**: No VM needed

## Parameters

| Parameter | Type   | Required | Default | Description              |
| --------- | ------ | -------- | ------- | ------------------------ |
| `image`   | string | Yes      | -       | Image UUID or `tag:name` |

## Response

```json theme={null}
{
  "uuid": "abc123-def456-...",
  "tag": "python:3.11",
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Examples

### By UUID

```json theme={null}
{"tool": "get_image", "args": {"image": "abc123-def456-..."}}
```

### By Tag

```json theme={null}
{"tool": "get_image", "args": {"image": "tag:python:3.11"}}
```

## See Also

* [list\_images](./list_images) - List all images
* [set\_tag](./set_tag) - Assign a tag


# get_operation
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/get_operation



Get the status and result of an operation.

## TL;DR

* **Use when**: Checking async operation results
* **Returns**: Operation state, stdout/stderr, exit code
* **Cost**: No VM needed

## Parameters

| Parameter      | Type   | Required | Default | Description    |
| -------------- | ------ | -------- | ------- | -------------- |
| `operation_id` | string | Yes      | -       | Operation UUID |

## Response

For instance (command) operations:

```json theme={null}
{
  "operation_kind": "instance",
  "state": "SUCCESS",
  "exit_code": 0,
  "stdout": "output here",
  "stderr": null,
  "result_image": "img-uuid",
  "resources": {
    "elapsed_time": 1.234
  }
}
```

For import operations:

```json theme={null}
{
  "operation_kind": "image_import",
  "state": "SUCCESS",
  "result_image": "img-uuid",
  "result_tag": "python:3.11"
}
```

## Examples

### Check Status

```json theme={null}
{"tool": "get_operation", "args": {
  "operation_id": "op-abc123"
}}
```

## Operation States

| State       | Description            |
| ----------- | ---------------------- |
| `PENDING`   | Queued                 |
| `EXECUTING` | Running                |
| `SUCCESS`   | Completed successfully |
| `FAILED`    | Completed with error   |
| `CANCELLED` | Cancelled              |

## See Also

* [wait\_operations](./wait_operations) - Wait for multiple ops
* [list\_operations](./list_operations) - List all operations
* [cancel\_operation](./cancel_operation) - Cancel running op


# import_image
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/import_image



Import OCI container image from registry. Spawns microVM.

**Check first**: Use `list_images` to see if already imported.

## Authentication

Before importing, authenticate with the registry:

1. Call `registry_token_obtain` to open browser for PAT creation
2. User creates read-only PAT in registry web UI
3. Call `registry_auth` to validate and store credentials

Anonymous access is possible but discouraged due to registry provider rate limits.

## Parameters

| Parameter                                              | Type    | Default  | Description                                 |
| ------------------------------------------------------ | ------- | -------- | ------------------------------------------- |
| `registry_url`                                         | string  | required | Registry URL (e.g., `docker://python:3.11`) |
| `tag`                                                  | string  | -        | Tag to assign after import                  |
| `wait`                                                 | boolean | `true`   | Wait for completion                         |
| `i_accept_that_anonymous_access_might_be_rate_limited` | boolean | `false`  | Skip authentication (not recommended)       |

## Examples

**Basic (requires prior authentication):**

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

**With tag:**

```json theme={null}
{"registry_url": "docker://alpine:latest", "tag": "alpine:latest"}
```

**Anonymous access (rate limited):**

```json theme={null}
{"registry_url": "docker://alpine:latest", "i_accept_that_anonymous_access_might_be_rate_limited": true}
```

**Async:**

```json theme={null}
{"registry_url": "docker://pytorch/pytorch:2.0-cuda11.7", "wait": false}
```

## Response

```json theme={null}
{"result_image": "abc123-uuid", "result_tag": "python:3.11", "state": "SUCCESS"}
```

With `wait=false`: `{"operation_id": "op-xxx"}`

## Common Base Images

| Registry URL                | Use Case      |
| --------------------------- | ------------- |
| `docker://python:3.11-slim` | Python        |
| `docker://node:20-slim`     | Node.js       |
| `docker://alpine:latest`    | Minimal Linux |
| `docker://ubuntu:22.04`     | Full Linux    |
| `docker://golang:1.21`      | Go            |

## Parallel Imports

```json theme={null}
{"registry_url": "docker://python:3.11", "wait": false}
{"registry_url": "docker://node:20", "wait": false}
{"tool": "wait_operations", "args": {"operation_ids": ["op-1", "op-2"]}}
```


# Tools Reference
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/index



All 17 tools for container execution, file management, and operations.

<Columns>
  <Card title="run" href="./run" icon="play" />

  <Card title="rsync" href="./rsync" icon="arrows-rotate" />

  <Card title="import_image" href="./import_image" icon="file-import" />

  <Card title="registry_token_obtain" href="./registry_token_obtain" icon="ticket" />

  <Card title="registry_auth" href="./registry_auth" icon="key" />

  <Card title="list_images" href="./list_images" icon="images" />

  <Card title="get_image" href="./get_image" icon="image" />

  <Card title="set_tag" href="./set_tag" icon="tag" />

  <Card title="upload" href="./upload" icon="upload" />

  <Card title="download" href="./download" icon="download" />

  <Card title="list_files" href="./list_files" icon="folder-open" />

  <Card title="read_file" href="./read_file" icon="file-lines" />

  <Card title="get_operation" href="./get_operation" icon="magnifying-glass" />

  <Card title="list_operations" href="./list_operations" icon="list-check" />

  <Card title="wait_operations" href="./wait_operations" icon="hourglass-half" />

  <Card title="cancel_operation" href="./cancel_operation" icon="ban" />

  <Card title="get_guide" href="./get_guide" icon="circle-question" />
</Columns>

## Quick Reference

### Command Execution

| Tool         | Description                  | Cost           |
| ------------ | ---------------------------- | -------------- |
| [run](./run) | Execute command in container | Spawns microVM |

### File Transfer

| Tool                   | Description                   | Cost  |
| ---------------------- | ----------------------------- | ----- |
| [rsync](./rsync)       | Sync local files with caching | No VM |
| [upload](./upload)     | Upload single file            | No VM |
| [download](./download) | Download file from image      | No VM |

### Image Management

| Tool                                               | Description                    | Cost           |
| -------------------------------------------------- | ------------------------------ | -------------- |
| [import\_image](./import_image)                    | Import from registry           | Spawns microVM |
| [registry\_token\_obtain](./registry_token_obtain) | Open browser for PAT creation  | No VM          |
| [registry\_auth](./registry_auth)                  | Validate and store credentials | No VM          |
| [list\_images](./list_images)                      | List available images          | No VM          |
| [get\_image](./get_image)                          | Get image by UUID/tag          | No VM          |
| [set\_tag](./set_tag)                              | Set or remove tag              | No VM          |

### Image Inspection

| Tool                        | Description          | Cost  |
| --------------------------- | -------------------- | ----- |
| [list\_files](./list_files) | List files in image  | No VM |
| [read\_file](./read_file)   | Read file from image | No VM |

### Operations

| Tool                                    | Description           | Cost  |
| --------------------------------------- | --------------------- | ----- |
| [get\_operation](./get_operation)       | Get operation status  | No VM |
| [list\_operations](./list_operations)   | List operations       | No VM |
| [wait\_operations](./wait_operations)   | Wait for multiple ops | No VM |
| [cancel\_operation](./cancel_operation) | Cancel operation      | No VM |

### Documentation

| Tool                      | Description        | Cost  |
| ------------------------- | ------------------ | ----- |
| [get\_guide](./get_guide) | Get guide sections | No VM |

## Common Patterns

### Basic Execution

```json theme={null}
{"tool": "run", "args": {"command": "python -c 'print(1)'", "image": "img-uuid"}}
```

### With Local Files

```json theme={null}
{"tool": "rsync", "args": {"source": "/project", "destination": "/app"}}
{"tool": "run", "args": {"command": "python /app/main.py", "image": "img-uuid", "directory_state_id": "ds-uuid"}}
```

### Parallel Execution

```json theme={null}
{"tool": "run", "args": {"command": "test1.py", "image": "img", "wait": false}}
{"tool": "run", "args": {"command": "test2.py", "image": "img", "wait": false}}
{"tool": "wait_operations", "args": {"operation_ids": ["op-1", "op-2"]}}
```

### Inspect Container (No VM)

```json theme={null}
{"tool": "list_files", "args": {"image": "img-uuid", "path": "/etc"}}
{"tool": "read_file", "args": {"image": "img-uuid", "path": "/etc/os-release"}}
```


# list_files
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/list_files



List files and directories in a container image without spawning a VM.

## Overview

`list_files` provides instant filesystem inspection without the overhead of starting a container. Use it to explore image contents, verify file existence, and check permissions before running commands.

## Parameters

| Parameter | Type   | Required | Default | Description              |
| --------- | ------ | -------- | ------- | ------------------------ |
| `image`   | string | Yes      | -       | Image UUID or `tag:name` |
| `path`    | string | No       | `/`     | Directory path to list   |

## Returns

| Field   | Type    | Description                     |
| ------- | ------- | ------------------------------- |
| `path`  | string  | Normalized path that was listed |
| `count` | integer | Number of entries in listing    |
| `files` | array   | List of file entries            |

### File Entry Fields

| Field    | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| `name`   | string  | File or directory name                |
| `path`   | string  | Full path within image                |
| `type`   | string  | `file`, `directory`, or `symlink`     |
| `size`   | integer | Size in bytes                         |
| `mode`   | string  | Octal permission mode (e.g., `0o755`) |
| `target` | string  | Symlink target (only for symlinks)    |

## Cost

**Free** - No VM spawned. Reads directly from image filesystem.

## Examples

### List Root Directory

```json theme={null}
{
  "tool": "list_files",
  "args": {
    "image": "abc123-def456",
    "path": "/"
  }
}
```

Response:

```json theme={null}
{
  "path": "/",
  "count": 15,
  "files": [
    {"name": "bin", "path": "/bin", "type": "symlink", "size": 0, "mode": "0o777", "target": "usr/bin"},
    {"name": "etc", "path": "/etc", "type": "directory", "size": 4096, "mode": "0o755", "target": null},
    {"name": "root", "path": "/root", "type": "directory", "size": 4096, "mode": "0o700", "target": null}
  ]
}
```

### List Specific Directory

```json theme={null}
{
  "tool": "list_files",
  "args": {
    "image": "tag:python:3.11-slim",
    "path": "/usr/local/lib/python3.11"
  }
}
```

### Verify File Existence Before Running

```json theme={null}
// Check if expected file exists
{"tool": "list_files", "args": {"image": "img-uuid", "path": "/app"}}

// If found, run the command
{"tool": "run", "args": {"command": "python /app/main.py", "image": "img-uuid"}}
```

## Best Practices

* **Prefer over `run("ls")`** - `list_files` is instant and free
* **Verify paths before commands** - Check files exist to avoid errors
* **Explore unfamiliar images** - Understand structure before running code
* **Check permissions** - Verify executable bits and ownership

## See Also

* [read\_file](./read_file) - Read file contents without VM
* [run](./run) - Execute commands (spawns VM)
* [Resources](../resources) - `contree://image/{image}/ls/{path}` resource alternative


# list_images
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/list_images



List available container images.

## TL;DR

* **Use when**: Finding images, checking before import
* **Returns**: List of images with UUID, tag, creation time
* **Cost**: No VM needed

## Parameters

| Parameter    | Type    | Required | Default | Description                      |
| ------------ | ------- | -------- | ------- | -------------------------------- |
| `limit`      | integer | No       | `100`   | Max images to return (1-1000)    |
| `offset`     | integer | No       | `0`     | Skip first N images              |
| `tagged`     | boolean | No       | `null`  | Only tagged images               |
| `tag_prefix` | string  | No       | `null`  | Filter by tag prefix             |
| `since`      | string  | No       | `null`  | Created after (e.g., “1h”, “1d”) |
| `until`      | string  | No       | `null`  | Created before                   |

## Response

```json theme={null}
{
  "images": [
    {
      "uuid": "abc123-def456-...",
      "tag": "python:3.11",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "uuid": "xyz789-...",
      "tag": null,
      "created_at": "2024-01-15T09:00:00Z"
    }
  ]
}
```

## Examples

### List All

```json theme={null}
{"tool": "list_images", "args": {}}
```

### Filter by Tag Prefix

```json theme={null}
{"tool": "list_images", "args": {"tag_prefix": "python"}}
```

### Only Tagged Images

```json theme={null}
{"tool": "list_images", "args": {"tagged": true}}
```

### Recent Images

```json theme={null}
{"tool": "list_images", "args": {"since": "1h"}}
```

### Pagination

```json theme={null}
{"tool": "list_images", "args": {"limit": 10, "offset": 20}}
```

## See Also

* [import\_image](./import_image) - Import new images
* [get\_image](./get_image) - Get single image details


# list_operations
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/list_operations



List operations (running or completed).

## TL;DR

* **Use when**: Finding operation IDs, monitoring
* **Returns**: List of operations with status
* **Cost**: No VM needed

## Parameters

| Parameter | Type    | Required | Default | Description              |
| --------- | ------- | -------- | ------- | ------------------------ |
| `limit`   | integer | No       | `100`   | Max operations to return |
| `status`  | string  | No       | `null`  | Filter by status         |
| `kind`    | string  | No       | `null`  | Filter by kind           |
| `since`   | string  | No       | `null`  | Created after            |

## Response

```json theme={null}
{
  "operations": [
    {
      "uuid": "op-abc123",
      "kind": "instance",
      "state": "SUCCESS",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

## Examples

### List Running

```json theme={null}
{"tool": "list_operations", "args": {"status": "running"}}
```

### List by Kind

```json theme={null}
{"tool": "list_operations", "args": {"kind": "image_import"}}
```

## See Also

* [get\_operation](./get_operation) - Get single operation
* [cancel\_operation](./cancel_operation) - Cancel operation


# read_file
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/read_file



Read a file from a container image without spawning a VM.

## Overview

`read_file` provides instant file content access without the overhead of starting a container. Use it to inspect configuration files, review scripts, or check expected content before running commands.

## Parameters

| Parameter | Type   | Required | Default | Description              |
| --------- | ------ | -------- | ------- | ------------------------ |
| `image`   | string | Yes      | -       | Image UUID or `tag:name` |
| `path`    | string | Yes      | -       | File path to read        |

## Returns

| Field        | Type    | Description                                     |
| ------------ | ------- | ----------------------------------------------- |
| `path`       | string  | Normalized path that was read                   |
| `content`    | string  | File contents (decoded or base64 encoded)       |
| `bytes_size` | integer | Size in bytes                                   |
| `encoding`   | string  | `"utf-8"` for text files, `"base64"` for binary |

## Cost

**Free** - No VM spawned. Reads directly from image filesystem.

## Text Detection

Files are automatically detected as text based on extension. Common text extensions include:

* Source code: `.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.c`, `.h`, `.cpp`
* Config: `.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.cfg`, `.conf`
* Scripts: `.sh`, `.bash`, `.zsh`
* Documentation: `.md`, `.rst`, `.txt`
* Web: `.html`, `.css`, `.xml`

Binary files are decoded with replacement characters for non-UTF8 bytes.

## Examples

### Read Configuration File

```json theme={null}
{
  "tool": "read_file",
  "args": {
    "image": "abc123-def456",
    "path": "/etc/os-release"
  }
}
```

Response:

```json theme={null}
{
  "path": "/etc/os-release",
  "content": "PRETTY_NAME=\"Debian GNU/Linux 12 (bookworm)\"\nNAME=\"Debian GNU/Linux\"\nVERSION_ID=\"12\"\n...",
  "bytes_size": 187,
  "encoding": "utf-8"
}
```

### Check Python Package Version

```json theme={null}
{
  "tool": "read_file",
  "args": {
    "image": "tag:python:3.11-slim",
    "path": "/usr/local/lib/python3.11/site-packages/pip/__init__.py"
  }
}
```

### Review Script Before Execution

```json theme={null}
// Read the script to understand what it does
{"tool": "read_file", "args": {"image": "img-uuid", "path": "/app/setup.sh"}}

// If safe, execute it
{"tool": "run", "args": {"command": "bash /app/setup.sh", "image": "img-uuid"}}
```

## Best Practices

* **Prefer over `run("cat")`** - `read_file` is instant and free
* **Review before executing** - Check scripts for safety before running
* **Inspect configurations** - Understand image setup without running commands
* **Verify expected content** - Check files contain what you expect

## See Also

* [list\_files](./list_files) - List directory contents without VM
* [download](./download) - Download file to local filesystem
* [Resources](../resources) - `contree://image/{image}/read/{path}` resource alternative


# registry_auth
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/registry_auth



Authenticate with a container registry via Personal Access Token.

## Parameters

| Parameter      | Type   | Default  | Description                                       |
| -------------- | ------ | -------- | ------------------------------------------------- |
| `registry_url` | string | required | Registry URL (e.g., `docker://ghcr.io/org/image`) |
| `username`     | string | required | Registry username                                 |
| `token`        | string | required | Personal Access Token                             |

## URL Parsing

| Input                                 | Registry             |
| ------------------------------------- | -------------------- |
| `docker://ghcr.io/org/image`          | ghcr.io              |
| `oci://registry.gitlab.com/org/image` | registry.gitlab.com  |
| `alpine` or `library/alpine`          | docker.io (implicit) |

## Examples

**Docker Hub:**

```json theme={null}
{"registry_url": "docker://docker.io/library/alpine", "username": "myuser", "token": "dckr_pat_xxx"}
```

**GitHub Container Registry:**

```json theme={null}
{"registry_url": "docker://ghcr.io/org/image", "username": "myuser", "token": "ghp_xxx"}
```

## Response

**Success:**

```json theme={null}
{
  "status": "success",
  "registry": "docker.io",
  "message": "Authenticated with 'docker.io' as 'myuser' successfully."
}
```

**Invalid credentials:**

```json theme={null}
{
  "status": "error",
  "registry": "docker.io",
  "message": "Invalid credentials for 'docker.io'. Please verify your username and PAT."
}
```

## Token Storage

* Credentials are validated via OCI /v2/ API before storage
* Stored in local cache and persisted across sessions
* Tokens are revalidated before each `import_image` call
* Expired tokens are automatically removed from cache

## Workflow

1. Call `registry_token_obtain` → opens browser
2. User creates read-only PAT in registry web UI
3. User provides username and token
4. Call `registry_auth` → validates and stores credentials
5. Call `import_image` to import images


# registry_token_obtain
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/registry_token_obtain



Open browser to create a Personal Access Token for a container registry.

## Parameters

| Parameter      | Type   | Default  | Description                                       |
| -------------- | ------ | -------- | ------------------------------------------------- |
| `registry_url` | string | required | Registry URL (e.g., `docker://ghcr.io/org/image`) |

## Known Registries

| Registry            | PAT Page                   |
| ------------------- | -------------------------- |
| docker.io           | Docker Hub PAT settings    |
| ghcr.io             | GitHub fine-grained tokens |
| registry.gitlab.com | GitLab PAT settings        |
| gcr.io              | Google Cloud credentials   |

## Examples

**Docker Hub:**

```json theme={null}
{"registry_url": "docker://docker.io/library/alpine"}
```

**GitHub Container Registry:**

```json theme={null}
{"registry_url": "docker://ghcr.io/org/image"}
```

**Bare image name (defaults to docker.io):**

```json theme={null}
{"registry_url": "alpine"}
```

## Response

**Success:**

```json theme={null}
{
  "status": "success",
  "registry": "docker.io",
  "url": "https://app.docker.com/settings/personal-access-tokens",
  "message": "Browser opened to ... Create a read-only PAT, then provide your username and token.",
  "agent_instruction": "STOP HERE. Wait for user to create PAT and provide the token."
}
```

**Unknown registry:**

```json theme={null}
{
  "status": "error",
  "registry": "unknown.example.com",
  "message": "Unknown registry 'unknown.example.com'. Please consult the registry documentation for token creation."
}
```

## Workflow

1. Call `registry_token_obtain` → opens browser
2. User creates read-only PAT in registry web UI
3. User provides username and token
4. Call `registry_auth` to validate and store credentials
5. Call `import_image` to import images


# rsync
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/rsync



Sync local files to Contree with smart caching. No VM needed.

## Parameters

| Parameter     | Type   | Default  | Description                |
| ------------- | ------ | -------- | -------------------------- |
| `source`      | string | required | Local path or glob pattern |
| `destination` | string | required | Container target directory |
| `exclude`     | array  | `[]`     | Patterns to exclude        |

## Examples

**Basic:**

```json theme={null}
{"source": "/project", "destination": "/app"}
```

**With exclusions:**

```json theme={null}
{
  "source": "/project",
  "destination": "/app",
  "exclude": ["__pycache__", "*.pyc", ".git", ".venv", "node_modules"]
}
```

**Glob pattern:**

```json theme={null}
{"source": "/project/**/*.py", "destination": "/app"}
```

## Response

Returns an integer `directory_state_id` for use with the `run` tool:

```json theme={null}
42
```

## Using with run

```json theme={null}
// 1. Sync
{"tool": "rsync", "args": {"source": "/project", "destination": "/app"}}
// Returns: 42

// 2. Run (reuse directory_state_id for multiple runs)
{"tool": "run", "args": {
  "command": "python /app/main.py",
  "image": "uuid",
  "directory_state_id": 42
}}
```

## Caching

Three-tier: local cache → content hash → server dedup. Only changed files upload.

**Tip:** Reuse `directory_state_id` for the session. Re-sync only when files change.

## Recommended Exclusions

```json theme={null}
["__pycache__", "*.pyc", ".git", ".venv", "node_modules", "*.log", ".DS_Store"]
```


# run
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/run



Execute command in isolated container. Spawns microVM (\~2-5s startup).

## Parameters

| Parameter            | Type    | Default  | Description                                                                                                  |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `command`            | string  | required | Shell command to execute                                                                                     |
| `image`              | string  | required | Image UUID or `tag:name`                                                                                     |
| `shell`              | boolean | `true`   | Whether command is a shell expression                                                                        |
| `disposable`         | boolean | `true`   | Discard changes after execution                                                                              |
| `directory_state_id` | integer | -        | Files from rsync                                                                                             |
| `files`              | object  | -        | Map of container paths to upload UUIDs: `{"/path/in/container": "uuid"}` — key is destination, value is UUID |
| `wait`               | boolean | `true`   | Block until complete                                                                                         |
| `timeout`            | integer | `30`     | Max seconds                                                                                                  |
| `env`                | object  | -        | Environment variables                                                                                        |
| `cwd`                | string  | `/root`  | Working directory                                                                                            |
| `stdin`              | string  | -        | Input via stdin                                                                                              |
| `truncate_output_at` | integer | `8000`   | Max bytes for output                                                                                         |

## Examples

**Basic:**

```json theme={null}
{"command": "python --version", "image": "tag:python:3.11"}
```

**With local files:**

```json theme={null}
{"command": "python /app/main.py", "image": "uuid", "directory_state_id": 42}
```

**Save changes:**

```json theme={null}
{"command": "pip install flask", "image": "uuid", "disposable": false}
```

Returns: `{"result_image": "new-uuid", "filesystem_changed": true}`

**Async:**

```json theme={null}
{"command": "python long_task.py", "image": "uuid", "wait": false}
```

Returns: `{"operation_id": "op-xxx"}`

**With uploaded files:**

```json theme={null}
// Step 1: Upload file
{"tool": "upload", "args": {"content": "print('hello')"}}
// Returns: {"uuid": "file-uuid-123"}

// Step 2: Inject into container and run
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "tag:python:3.11",
  "files": {"/app/script.py": "file-uuid-123"}
}}
```

> **Common mistake:** The `files` key is the **container path** (destination), the value is the **UUID** (from upload). Not the other way around. One UUID can be mounted to multiple paths.

**Environment variables:**

```json theme={null}
{"command": "echo $MY_VAR", "image": "uuid", "env": {"MY_VAR": "hello"}}
```

## Response

```json theme={null}
{
  "exit_code": 0,
  "timed_out": false,
  "state": "SUCCESS",
  "result_image": "uuid-if-disposable-false",
  "filesystem_changed": true,
  "stdout": "output",
  "stderr": null
}
```

## Errors

* **Image not found**: Use `list_images` to find valid UUIDs
* **Directory state not found**: Re-run `rsync`
* **timed\_out: true**: Increase `timeout` parameter


# set_tag
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/set_tag



Set or remove a tag for an image.

## TL;DR

* **Use when**: Naming frequently-used images
* **Returns**: Updated image details
* **Cost**: No VM needed

## Parameters

| Parameter    | Type   | Required | Default | Description                    |
| ------------ | ------ | -------- | ------- | ------------------------------ |
| `image_uuid` | string | Yes      | -       | Image UUID to tag              |
| `tag`        | string | No       | `null`  | Tag to assign (omit to remove) |

## Response

```json theme={null}
{
  "uuid": "abc123-def456-...",
  "tag": "my-image:v1",
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Examples

### Set Tag

```json theme={null}
{"tool": "set_tag", "args": {
  "image_uuid": "abc123-def456-...",
  "tag": "claude/project/python/dev-env:v1"
}}
```

### Remove Tag

```json theme={null}
{"tool": "set_tag", "args": {
  "image_uuid": "abc123-def456-..."
}}
```

## Tagging Convention

For AI agents, use this pattern:

```
{agent}/{project}/{base}/{approach}:{version}
```

Examples:

* `claude/myproject/python/dev-env:v1`
* `claude/common/alpine/build-tools:latest`

## See Also

* [get\_image](./get_image) - Get image details
* [list\_images](./list_images) - Find images


# upload
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/upload



Upload a file to Contree.

## TL;DR

* **Use when**: Single file, generated content
* **Returns**: File UUID for use with `run`
* **Cost**: No VM needed
* **Prefer**: `rsync` for multiple files (has caching)

## Parameters

| Parameter        | Type   | Required | Default | Description                                                                                                                                                                                        |
| ---------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`        | string | No\*     | -       | Text content                                                                                                                                                                                       |
| `content_base64` | string | No\*     | -       | Base64-encoded binary                                                                                                                                                                              |
| `path`           | string | No\*     | -       | Absolute path to a file on **local filesystem** to read and upload. Not a destination name — files are content-addressable (UUID). To name the file in a container, use `run`’s `files` parameter. |

\*One of `content`, `content_base64`, or `path` is required.

## Response

```json theme={null}
{
  "uuid": "file-uuid-123",
  "sha256": "abc123..."
}
```

## Examples

### Text Content

```json theme={null}
{"tool": "upload", "args": {
  "content": "print('hello world')"
}}
```

### Local File

```json theme={null}
{"tool": "upload", "args": {
  "path": "/path/to/script.py"
}}
```

### Binary (Base64)

```json theme={null}
{"tool": "upload", "args": {
  "content_base64": "SGVsbG8gV29ybGQ="
}}
```

## Using the Result

Pass the UUID to `run` via the `files` parameter:

```json theme={null}
// Step 1: Upload
{"tool": "upload", "args": {"content": "print('hello')"}}
// Returns: {"uuid": "file-uuid-123"}

// Step 2: Run
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "img-uuid",
  "files": {"/app/script.py": "file-uuid-123"}
}}
```

## Common Mistake

`path` reads from the **local MCP-server filesystem** — it does not set the file’s name in storage. The uploaded file is content-addressable and identified only by UUID. To place it at a specific path inside a container, pass the UUID to `run`’s `files` parameter:

```json theme={null}
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "img-uuid",
  "files": {"/app/script.py": "file-uuid-123"}
}}
```

## See Also

* [rsync](./rsync) - For multiple files (with caching)
* [run](./run) - Use uploaded files
* [download](./download) - Download from images


# wait_operations
Source: https://docs.tokenfactory.nebius.com/sandboxes/mcp/tools/wait_operations



Wait for multiple operations to complete.

## TL;DR

* **Use when**: Launched multiple async operations
* **Returns**: All operation results
* **Cost**: No VM needed (just waiting)

## Parameters

| Parameter       | Type   | Required | Default | Description             |
| --------------- | ------ | -------- | ------- | ----------------------- |
| `operation_ids` | array  | Yes      | -       | List of operation UUIDs |
| `mode`          | string | No       | `"all"` | `"all"` or `"any"`      |
| `timeout`       | number | No       | `300`   | Max wait time (seconds) |

## Response

```json theme={null}
{
  "results": {
    "op-1": {
      "state": "SUCCESS",
      "exit_code": 0,
      "stdout": "..."
    },
    "op-2": {
      "state": "SUCCESS",
      "exit_code": 0,
      "stdout": "..."
    }
  },
  "completed": ["op-1", "op-2"],
  "cancelled": [],
  "timed_out": false
}
```

## Examples

### Wait for All

```json theme={null}
{"tool": "wait_operations", "args": {
  "operation_ids": ["op-1", "op-2", "op-3"]
}}
```

### Wait for Any (First to Complete)

```json theme={null}
{"tool": "wait_operations", "args": {
  "operation_ids": ["op-1", "op-2", "op-3"],
  "mode": "any"
}}
```

### With Timeout

```json theme={null}
{"tool": "wait_operations", "args": {
  "operation_ids": ["op-1", "op-2"],
  "timeout": 600
}}
```

## Parallel Execution Pattern

```json theme={null}
// Launch async
{"tool": "run", "args": {"command": "test1.py", "wait": false}}
{"tool": "run", "args": {"command": "test2.py", "wait": false}}
{"tool": "run", "args": {"command": "test3.py", "wait": false}}

// Wait for all
{"tool": "wait_operations", "args": {
  "operation_ids": ["op-1", "op-2", "op-3"]
}}
```

## See Also

* [get\_operation](./get_operation) - Check single operation
* [Async Guide](../resources#guide) - Parallel execution patterns


# Overview
Source: https://docs.tokenfactory.nebius.com/sandboxes/overview



<Note>
  Sandboxes are currently in Beta. We value your feedback, please send us email to [contree@nebius.com](mailto:contree@nebius.com) or reach out in [Discord](https://discord.com/channels/1222156136380235877/1476967257585221845).
</Note>

Sandboxes is a cloud-based sandbox API by Nebius that enables secure code execution with Git-like branching capabilities. It is built for AI agents that need to explore multiple execution paths, evaluate outcomes, and backtrack when necessary.

Sandboxes combines VM-level isolation with container efficiency, providing a secure environment for executing untrusted code. Unlike traditional containers, Sandboxes supports Git-like branching — fork from any checkpoint, run parallel explorations, and roll back instantly.

## Key features

<Columns>
  <Card title="Secure isolation" icon="shield-check">
    VM-level isolation ensures untrusted code cannot escape the sandbox or affect other workloads.
  </Card>

  <Card title="Git-like branching" icon="code-branch">
    Fork execution state at any checkpoint. Explore multiple solution paths in parallel, then score results and expand the best branches.
  </Card>

  <Card title="Instant rollback" icon="rotate-left">
    Return to any previous state with a single API call. No need to rebuild or re-execute from scratch.
  </Card>

  <Card title="OCI image support" icon="cube">
    Import images from any OCI-compliant registry (Docker Hub, GHCR, and others). Use your existing container images as sandbox bases.
  </Card>

  <Card title="Resource metrics" icon="chart-line">
    Built-in tracking of CPU time, memory usage, and I/O operations for every execution.
  </Card>

  <Card title="Async operations" icon="clock">
    All long-running operations (image imports, executions) are async with polling support and cancellation.
  </Card>
</Columns>

## Quick start

<Steps>
  <Step title="Choose a base state">
    Start from a preloaded environment, a previously produced checkpoint, or an imported OCI image.
  </Step>

  <Step title="Make inputs explicit">
    Attach the files and runtime assumptions the command needs so the run can be replayed later.
  </Step>

  <Step title="Start an execution">
    Run code inside the sandbox from the chosen state. Long-running work is represented as an operation.
  </Step>

  <Step title="Wait for the operation">
    Poll through the CLI, SDK, or generated client until execution reaches a terminal state.
  </Step>

  <Step title="Inspect the resulting checkpoint">
    Read logs, metrics, files, and artifacts from the state produced by the run.
  </Step>

  <Step title="Branch when needed">
    Fork from any useful checkpoint to try alternatives, compare outcomes, and continue from the best branch.
  </Step>
</Steps>

## Use cases

<Columns>
  <Card title="AI coding agents" icon="robot">
    Let AI agents execute and test code safely. Branch to explore multiple approaches, evaluate results, and continue the most promising path.
  </Card>

  <Card title="Research and experimentation" icon="flask">
    Run experiments in isolated environments. Fork state to test variations without starting over.
  </Card>

  <Card title="Educational platforms" icon="graduation-cap">
    Provide students with safe code execution environments. Automatic cleanup and resource limits help prevent abuse.
  </Card>

  <Card title="CI/CD pipelines" icon="gears">
    Execute build steps and tests in isolated sandboxes with full resource tracking and artifact retrieval.
  </Card>
</Columns>

<Warning>
  **Beta limitations**

  * Number of simultaneously running operations is limited to 50.
  * Checkpoint images retention is set to 180 days. After this period we may delete untagged unreferenced images (those that do not produce any other images).

  Please contact us if you need those limitations lifted for the beta period.
</Warning>

## Resources

* [Sandboxes for SWE agents](/sandboxes/swe-agents) — Preloaded environments and Hugging Face datasets
* [Contree SDK](/sandboxes/sdk) — Python SDK for programmatic access to the Sandboxes API
* [Contree CLI](/sandboxes/cli) — Terminal client for interactive and scripted sandbox workflows
* [Contree MCP](/sandboxes/mcp) — Model Context Protocol server for AI assistants


# Overview
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/index



[![PyPI version](https://img.shields.io/pypi/v/contree-sdk.svg?style=flat-square)](https://pypi.org/project/contree-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/contree-sdk?style=flat-square)](https://pypi.org/project/contree-sdk/)

ConTree is a container runtime, providing **reproducible, versioned filesystem state** — like Git for container execution. The SDK makes this accessible from Python.

## Quick Start

### Installation

Install the SDK from PyPi:

```bash theme={null}
pip install contree-sdk
```

### Basic Usage

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("busybox:latest")
    print(f"Using {image=}")

    result = await image.run(shell="echo 'Hello World'")
    print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    result = await image.run(shell="pwd")
    print(f"Current directory: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="ls -la")
    print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="cat -", stdin="Hello from stdin\n")
    print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="echo 'Error message' >&2; exit 1")
    print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("busybox:latest")
    print(f"Using {image=}")

    result = image.run(shell="echo 'Hello World'").wait()
    print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    result = image.run(shell="pwd").wait()
    print(f"Current directory: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="ls -la").wait()
    print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="cat -", stdin="Hello from stdin\n").wait()
    print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="echo 'Error message' >&2; exit 1").wait()
    print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```
  </Tab>
</Tabs>

## What’s Next?

Ready to explore more? Check out our guides:

<Columns>
  <Card title="Getting Started" href="./python_sdk/getting-started" icon="hand-wave">
    Detailed setup and basic operations.
  </Card>

  <Card title="Working with Images" href="./python_sdk/images" icon="layer-group">
    Pull and import container images.
  </Card>

  <Card title="Running Commands" href="./python_sdk/running-commands" icon="terminal">
    Comprehensive guide to command execution.
  </Card>

  <Card title="Branching Workflows" href="./python_sdk/branching" icon="code-branch">
    Create reproducible execution branches.
  </Card>
</Columns>


# Integrations
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/integrations/index



<Columns>
  <Card title="Mini-SWE-Agent Integration" href="./mini-swe-agent" icon="robot" />

  <Card title="LangChain Integration" href="./langchain" icon="robot" />
</Columns>


# LangChain Integration
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/integrations/langchain



[LangChain](https://python.langchain.com/) is a popular framework for building AI agents.
The ConTree integration provides a `ContreeSandbox` backend that lets LangChain agents execute code in isolated, reproducible containers.

Integration is available via `contree-sdk[langchain]`, which provides `ContreeSandbox` — an implementation of [`BaseSandbox`](https://docs.langchain.com/oss/python/deepagents/backends/sandbox) from the [deepagents](https://pypi.org/project/deepagents/) package.

## Using ContreeSandbox

```python theme={null}
import asyncio
import os

from deepagents import create_deep_agent
from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI
from pydantic import SecretStr

from contree_sdk import Contree
from contree_sdk.langchain.sandbox import ContreeSandbox


async def main():
    client = Contree()
    image = await client.images.oci("python:3.13-slim")
    session = image.session()
    sandbox = ContreeSandbox(session=session)

    model = ChatOpenAI(
        model="zai-org/GLM-5.2",
        base_url="https://api.studio.nebius.ai/v1/",
        api_key=SecretStr(os.environ["NEBIUS_API_KEY"]),
    )

    agent = create_deep_agent(model=model, backend=sandbox)
    result = await agent.ainvoke({"messages": [HumanMessage("Develop a small calculator script and run it")]})
    print(result["messages"][-1].content)


if __name__ == "__main__":
    asyncio.run(main())
```

## Setup

1. Install the dependencies:

   ```bash theme={null}
   pip install "contree-sdk[langchain]"
   ```
2. Set up Nebius IAM token and base URL:

   ```bash theme={null}
   export NEBIUS_API_KEY="your-nebius-iam-token"
   export NEBIUS_PROJECT_ID="your-project-id"
   ```
3. Set up your LLM provider credentials (e.g. for Anthropic):

   ```bash theme={null}
   export ANTHROPIC_API_KEY="your-anthropic-api-key"
   ```


# Mini-SWE-Agent Integration
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/integrations/mini-swe-agent



[Mini-SWE-Agent](https://mini-swe-agent.com/latest/) is a lightweight software engineering agent.
The ConTree integration enables it to execute code in isolated, reproducible containers. Every command in Mini-SWE-Agent is executed in a fresh shell session, which makes it perfectly suitable for ConTree.

Integration is available via [ContreeEnvironment](https://mini-swe-agent.com/latest/reference/environments/contree/) starting from [mini-swe-agent v2.2.0](https://github.com/SWE-agent/mini-swe-agent/releases/tag/v2.2.0).

## Using ContreeEnvironment

```python theme={null}
from minisweagent.agents.default import DefaultAgent
from minisweagent.environments.extra.contree import ContreeEnvironment
from minisweagent.models import get_model

from contree_sdk.auth import IAMAuth
from contree_sdk.config import ContreeConfig


def main():
    contree_env = ContreeEnvironment(
        contree_config=ContreeConfig(
            auth=IAMAuth(base_url="https://contree.dev/"),
        ),
        image="python:3.13-slim",
        cwd="/workspace",
    )

    agent = DefaultAgent(
        get_model(input_model_name="gemini/gemini-flash-latest"), contree_env, system_template="", instance_template=""
    )
    agent.run("Develop small calculator script and check it")

    result = contree_env.session.run(shell="ls /workspace -lah").wait()
    print(result.stdout)


if __name__ == "__main__":
    main()
```

## Running with SWE-bench

### Setup

1. Install the dependencies:

   ```bash theme={null}
   pip install "mini-swe-agent[contree]"
   ```
2. Set up Nebius IAM token and base URL:

   ```bash theme={null}
   export NEBIUS_API_KEY="your-nebius-iam-token"
   export NEBIUS_PROJECT_ID="your-project-id"
   export CONTREE_BASE_URL="your-given-base-url-for-contree"
   ```

### Usage

Run mini-swe-agent like with any other environment:

```bash theme={null}
mini-extra swebench \
    --subset verified \
    --split test \
    --workers 100
    --environment-class contree
```

It can be specified both through cli parameter or by setting `environment_class` to `contree` in your swebench.yaml config


# Branching Workflows
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/branching



One of ConTree’s most powerful features is the ability to branch execution flows from a single base filesystem state (a snapshot of all files and directories in a container at a specific point in time). This is similar to Git branches, but for container execution states.

## Why Branching Matters

Without ConTree, running the same operations twice (like installing packages, creating files, or compiling code) requires rebuilding the entire filesystem state from scratch each time. ConTree captures the exact filesystem state after each command, making it reproducible and allowing you to branch from that exact state.

## Simple Branching Example

This example demonstrates creating a parent state with a random value, then branching into multiple child states from that fixed parent:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    base = await client.images.use("alpine:latest")

    child = await base.run(shell='echo "$RANDOM" > /tmp/random.txt', disposable=False)
    print(f"Child created from base, UUID: {child.uuid}\n")

    for i, letter in enumerate(["A", "B", "C"], 1):
        gc = await child.run(
            shell=f"echo '{letter}' >> /tmp/random.txt && cat /tmp/random.txt",
            disposable=False,
        )
        print(f"Grandchild {i}: {gc.stdout.strip()}")
    ```

    See [`run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.run) for full API reference.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    base = client.images.use("alpine:latest")

    child = base.run(shell='echo "$RANDOM" > /tmp/random.txt', disposable=False).wait()
    print(f"Child created from base, UUID: {child.uuid}\n")

    for i, letter in enumerate(["A", "B", "C"], 1):
        gc = child.run(
            shell=f"echo '{letter}' >> /tmp/random.txt && cat /tmp/random.txt",
            disposable=False,
        ).wait()
        print(f"Grandchild {i}: {gc.stdout.strip()}")
    ```

    See [`run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.run) for full API reference.
  </Tab>
</Tabs>

**Key Points:**

* The `child` state contains a random value that would be different on each execution without ConTree
* All three grandchildren start from the exact same `child` state (same random value)
* Each grandchild branches independently, creating different execution paths

## Advanced Branching Patterns

For more complex scenarios with multiple branching strategies:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("alpine:latest")
    print(f"Using {image=}")

    print("\nExample 1: Different commands from same image")
    result1 = await image.run(shell="echo 'First branch'", disposable=False)
    result2 = await image.run(shell="echo 'Second branch'", disposable=False)
    result3 = await image.run(shell="ls /bin | head -3", disposable=False)

    print(f"Branch 1: {result1.stdout=}, {result1.uuid=}")
    print(f"Branch 2: {result2.stdout=}, {result2.uuid=}")
    print(f"Branch 3: {result3.stdout=}, {result3.uuid=}")

    print("\nExample 2: Random output command (different each time)")
    random1 = await image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False)
    random2 = await image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False)

    print(f"Random 1: {random1.stdout=}, {random1.uuid=}")
    print(f"Random 2: {random2.stdout=}, {random2.uuid=}")

    print("\nExample 3: Chain of operations from different branches")
    base_result = await image.run(shell="echo 'apple\nbanana\ncherry' > /tmp/fruits.txt", disposable=False)

    sort_result = await base_result.run(shell="sort /tmp/fruits.txt", disposable=False)
    reverse_result = await base_result.run(shell="sort -r /tmp/fruits.txt", disposable=False)

    print(f"Base: {base_result.uuid=}")
    print(f"Sorted: {sort_result.stdout=}, {sort_result.uuid=}")
    print(f"Reverse sorted: {reverse_result.stdout=}, {reverse_result.uuid=}")

    print("\nExample 4: Same command twice - same UUID")
    same1 = await image.run(shell="echo 'Same command'", disposable=False)
    same2 = await image.run(shell="echo 'Same command'", disposable=False)

    print(f"Same 1: {same1.stdout=}, {same1.uuid=}")
    print(f"Same 2: {same2.stdout=}, {same2.uuid=}")
    print(f"UUIDs equal: {same1.uuid == same2.uuid}")
    ```

    See [`ContreeImage`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage) for full API reference.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("alpine:latest")
    print(f"Using {image=}")

    print("\nExample 1: Different commands from same image")
    result1 = image.run(shell="echo 'First branch'", disposable=False).wait()
    result2 = image.run(shell="echo 'Second branch'", disposable=False).wait()
    result3 = image.run(shell="ls /bin | head -3", disposable=False).wait()

    print(f"Branch 1: {result1.stdout=}, {result1.uuid=}")
    print(f"Branch 2: {result2.stdout=}, {result2.uuid=}")
    print(f"Branch 3: {result3.stdout=}, {result3.uuid=}")

    print("\nExample 2: Random output command (different each time)")
    random1 = image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False).wait()
    random2 = image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False).wait()

    print(f"Random 1: {random1.stdout=}, {random1.uuid=}")
    print(f"Random 2: {random2.stdout=}, {random2.uuid=}")

    print("\nExample 3: Chain of operations from different branches")
    base_result = image.run(shell="echo 'apple\nbanana\ncherry' > /tmp/fruits.txt", disposable=False).wait()

    sort_result = base_result.run(shell="sort /tmp/fruits.txt", disposable=False).wait()
    reverse_result = base_result.run(shell="sort -r /tmp/fruits.txt", disposable=False).wait()

    print(f"Base: {base_result.uuid=}")
    print(f"Sorted: {sort_result.stdout=}, {sort_result.uuid=}")
    print(f"Reverse sorted: {reverse_result.stdout=}, {reverse_result.uuid=}")

    print("\nExample 4: Same command twice - same UUID")
    same1 = image.run(shell="echo 'Same command'", disposable=False).wait()
    same2 = image.run(shell="echo 'Same command'", disposable=False).wait()

    print(f"Same 1: {same1.stdout=}, {same1.uuid=}")
    print(f"Same 2: {same2.stdout=}, {same2.uuid=}")
    print(f"UUIDs equal: {same1.uuid == same2.uuid}")
    ```

    See [`ContreeImageSync`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync) for full API reference.
  </Tab>
</Tabs>

## Use Cases

Branching is particularly useful for:

* **Testing multiple scenarios**: Run different operations from the same starting state
* **Reproducible randomness**: Capture random/non-deterministic operations and branch from them
* **Parallel execution paths**: Execute different workflows from a common checkpoint
* **Version control for execution**: Create branches like Git for different execution flows


# Getting Started
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/getting-started



This guide will help you get up and running with ConTree SDK. By the end of this guide, you’ll understand how to create clients, work with images, and run your first commands.

## Configuration

The SDK resolves credentials in the following priority order:

1. **Explicit values** passed to `IAMAuth` / `JWTAuth` constructors via `ContreeConfig`.
2. **Environment variables**:

   * `NEBIUS_API_KEY` — IAM token
   * `NEBIUS_PROJECT_ID` — ConTree project ID
   * `CONTREE_BASE_URL` — ConTree instance URL (for `JWTAuth`)
3. **`auth.ini`** — if the `contree` CLI is installed, credentials written by `contree auth` are read automatically from `~/.config/contree/auth.ini`.

```bash theme={null}
export NEBIUS_API_KEY="your_token_here"
export NEBIUS_PROJECT_ID="your_project_id"
export CONTREE_BASE_URL="https://your-instance.of.contree"
```

The active `auth.ini` profile defaults to `default` and can be overridden with `CONTREE_PROFILE`. The config directory respects `$CONTREE_HOME` and `$XDG_CONFIG_HOME`.

Alternatively, you can pass auth directly when creating a client via `ContreeConfig(auth=IAMAuth(...))` or use `JWTAuth` for legacy token-based access.

## Creating a Client

The first step is to create a ConTree client. You can choose between async and sync versions depending on your application needs.

Here’s how to create a client and verify the connection by listing available images:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    # Get client
    client = Contree()

    # Get images (to verify that connection works)
    await client.images()
    ```

    See [`Contree`](./reference/client#contree_sdk.Contree) for all client options.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    # Get client
    client = ContreeSync()

    # Get images (to verify that connection works)
    client.images()
    ```

    See [`ContreeSync`](./reference/client#contree_sdk.ContreeSync) for all client options.
  </Tab>
</Tabs>

## Working with Images

Images are the foundation of ConTree. The simplest way to reference an image is by tag using `images.use()`, which creates an image object without making an API call:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await contree.images.use("ubuntu:latest")
    result = await image.run(shell="echo hello")
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = contree.images.use("ubuntu:latest")
    result = image.run(shell="echo hello").wait()
    ```
  </Tab>
</Tabs>

To resolve a tag or UUID upfront via an API call, use `images.use(strict=True)`. To import from an external registry (or return an existing image if already imported), use `images.oci()`.

See [Working with Images](./images) for a full overview of available methods, examples, and what you can pass as a reference.

## Running Commands

Once you have an image, you can run commands inside it. Each command execution creates a new version of the image with your changes.

### Basic Command Execution

You can run various shell commands and handle their output:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("busybox:latest")
    print(f"Using {image=}")

    result = await image.run(shell="echo 'Hello World'")
    print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    result = await image.run(shell="pwd")
    print(f"Current directory: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="ls -la")
    print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="cat -", stdin="Hello from stdin\n")
    print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="echo 'Error message' >&2; exit 1")
    print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```

    See [`run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.run) for all command execution options.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("busybox:latest")
    print(f"Using {image=}")

    result = image.run(shell="echo 'Hello World'").wait()
    print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    result = image.run(shell="pwd").wait()
    print(f"Current directory: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="ls -la").wait()
    print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="cat -", stdin="Hello from stdin\n").wait()
    print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="echo 'Error message' >&2; exit 1").wait()
    print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```

    See [`run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.run) for all command execution options.
  </Tab>
</Tabs>

### Understanding the Results

When you run a command, you get back a result object that contains:

* **`stdout`**: Standard output from the command
* **`stderr`**: Standard error from the command
* **`exit_code`**: The exit code (0 for success, non-zero for errors)
* **`uuid`**: The UUID of the new image version created by this command


# Working with Images
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/images



ConTree SDK provides several ways to reference and import container images. For full API documentation, see [`ImagesManager`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager) and [`ImagesManagerSync`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync).

## Using Images by Tag

The simplest way to get an image is `images.use(tag)`. This creates an image object immediately without any API call — the tag is resolved at execution time when you run a command:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await contree.images.use("ubuntu:latest")
    result = await image.run(shell="echo hello")
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = contree.images.use("ubuntu:latest")
    result = image.run(shell="echo hello").wait()
    ```
  </Tab>
</Tabs>

## Pulling Images

For resolving a tag/UUID to an image upfront, use `images.use(strict=True)`. For importing images from external registries, use `images.oci()`:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    print(f"Selected {image_uuid=}")
    print(f"Selected {image_tag=}")

    print("\nPulling by UUID (strict):")
    result = await client.images.use(image_uuid, strict=True)
    print(f"Pulled by UUID: {result.uuid=}, {result.tag=}, {result.state=}")

    print("\nPulling by tag (strict):")
    result = await client.images.use(image_tag, strict=True)
    print(f"Pulled by tag: {result.uuid=}, {result.tag=}, {result.state=}")

    print("\nImporting public image using oci:")
    result = await client.images.oci("docker://ghcr.io/linuxserver/code-server:latest")
    print(f"Pulled public: {result.uuid=}, {result.tag=}, {result.state=}")
    ```

    See [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.use) and [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.oci) for all parameters.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    print(f"Selected {image_uuid=}")
    print(f"Selected {image_tag=}")

    print("\nPulling by UUID (strict):")
    result = client.images.use(image_uuid, strict=True)
    print(f"Pull by UUID: {result.uuid=}, {result.tag=}, {result.state=}")

    print("\nPulling by tag (strict):")
    result = client.images.use(image_tag, strict=True)
    print(f"Pull by tag: {result.uuid=}, {result.tag=}, {result.state=}")

    print("\nImporting public image using oci:")
    result = client.images.oci("docker://ghcr.io/linuxserver/code-server:latest")
    print(f"Import public: {result.uuid=}, {result.tag=}, {result.state=}")
    ```

    See [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.use) and [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.oci) for all parameters.
  </Tab>
</Tabs>

### Methods

<Tabs>
  <Tab title="Async">
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.use)(ref) — no API call; tag or UUID is resolved at execution time
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.use)(ref, strict=True) — verifies the image exists via an API call
    * [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.oci)(ref) (aliases: [`docker()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.docker), [`podman()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.podman), [`pull_by_oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.pull_by_oci)) — like `use(strict=True)`, but imports from the registry if not found locally
    * [`import_from()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.import_from)(ref) — always imports from an external registry
  </Tab>

  <Tab title="Sync">
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.use)(ref) — no API call; tag or UUID is resolved at execution time
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.use)(ref, strict=True) — verifies the image exists via an API call
    * [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.oci)(ref) (aliases: [`docker()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.docker), [`podman()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.podman), [`pull_by_oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.pull_by_oci)) — like `use(strict=True)`, but imports from the registry if not found locally
    * [`import_from()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.import_from)(ref) — always imports from an external registry
  </Tab>
</Tabs>

<Danger>
  `import_from` always triggers a new import operation and should only be used when you explicitly need to re-import. In most cases, prefer `images.oci()`, which returns an existing image if already imported. If no import is needed at all, use `images.use()`.
</Danger>

### What `ref` can be

* UUID — reference an existing image by its UUID, e.g. `"550e8400-e29b-41d4-a716-446655440000"` or `UUID(...)`
* OCI tag — reference by image tag, e.g. `"ubuntu:latest"`
* OCI full URL — full reference including registry host, e.g. `"docker://ghcr.io/owner/image:tag"`
* [`OCIReference`](./reference/oci#contree_sdk.utils.oci.OCIReference) — programmatic OCI reference object

## Tagging Images

You can assign or remove a tag on any image using `tag_as()` and `untag()`. Tags are unique across all images — assigning an existing tag to a new image moves it automatically.

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use(image_tag, strict=True)
    print(f"Original: {image.uuid=}, {image.tag=}")

    tagged = await image.tag_as("my-custom-tag:v1")
    print(f"After tag_as: {tagged.uuid=}, {tagged.tag=}")

    untagged = await tagged.untag()
    print(f"After untag: {untagged.uuid=}, {untagged.tag=}")

    result = await image.run(shell="echo hello", tag="my-result:v1", disposable=False)
    print(f"Run result: {result.uuid=}, {result.tag=}")
    ```

    See [`tag_as()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.tag_as) and [`untag()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.untag) for details.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use(image_tag, strict=True)
    print(f"Original: {image.uuid=}, {image.tag=}")

    tagged = image.tag_as("my-custom-tag:v1")
    print(f"After tag_as: {tagged.uuid=}, {tagged.tag=}")

    untagged = tagged.untag()
    print(f"After untag: {untagged.uuid=}, {untagged.tag=}")

    result = image.run(shell="echo hello", tag="my-result:v1", disposable=False).wait()
    print(f"Run result: {result.uuid=}, {result.tag=}")
    ```

    See [`tag_as()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.tag_as) and [`untag()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.untag) for details.
  </Tab>
</Tabs>

You can also tag the result of a `run()` directly by passing `tag=` to the call — the resulting image will be tagged after execution completes:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    result = await image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False)
    print(result.tag)  # "myapp:ready"
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    result = image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False).wait()
    print(result.tag)  # "myapp:ready"
    ```
  </Tab>
</Tabs>

## Listing Images

View all available images in your ConTree instance:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    all_images = await client.images()
    print(f"Loaded {all_images=}")

    limited_images = await client.images(number=3)
    print(f"Found {len(limited_images)=}")

    tagged_images = await client.images(tagged=True)
    print(f"Found {len(tagged_images)=}")

    imported_images = await client.images(kind=ImageKind.IMPORTED)
    print(f"Found {len(imported_images)=}")

    recent_images = await client.images(since=datetime.now() - timedelta(days=7), number=5)
    print(f"Found {len(recent_images)=}")
    ```

    See [`ImagesManager`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager) for filtering and iteration options.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    all_images = client.images()
    print(f"Loaded {all_images=}")

    limited_images = client.images(number=3)
    print(f"Found {len(limited_images)=}")

    tagged_images = client.images(tagged=True)
    print(f"Found {len(tagged_images)=}")

    imported_images = client.images(kind=ImageKind.IMPORTED)
    print(f"Found {len(imported_images)=}")

    recent_images = client.images(since=datetime.now() - timedelta(days=7), number=5)
    print(f"Found {len(recent_images)=}")
    ```

    See [`ImagesManagerSync`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync) for filtering and iteration options.
  </Tab>
</Tabs>


# Auth
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/auth



<a />

## `class Auth`

```python theme={null}
class contree_sdk.auth.Auth(base_url)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="base_url" type="str">
    API server URL or env var name to load from.
  </ResponseField>

  ### Methods

  <a />

  #### `resolve()`

  ```python theme={null}
  def resolve() -> Self
  ```

  <ResponseField name="returns" type="Self" />

  <a />

  #### `get_headers()`

  ```python theme={null}
  @abstractmethod
  def get_headers() -> dict[str, str]
  ```

  <ResponseField name="returns" type="dict[str, str]" />
</div>

<a />

## `class JWTAuth`

```python theme={null}
class contree_sdk.auth.JWTAuth(base_url, token)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="token" type="str">
    Auth token or env var name to load from.
  </ResponseField>

  <a />

  <ResponseField name="base_url" type="str">
    API server URL or env var name to load from.
  </ResponseField>

  ### Methods

  <a />

  #### `get_headers()`

  ```python theme={null}
  def get_headers() -> dict[str, str]
  ```

  <ResponseField name="returns" type="dict[str, str]" />

  <a />

  #### `resolve()`

  ```python theme={null}
  def resolve() -> Self
  ```

  <ResponseField name="returns" type="Self" />
</div>

<a />

## `class IAMAuth`

```python theme={null}
class contree_sdk.auth.IAMAuth(base_url, token, project_id)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="token" type="str">
    IAM token or env var name to load from.
  </ResponseField>

  <a />

  <ResponseField name="project_id" type="str">
    Nebius project ID or env var name to load from.
  </ResponseField>

  <a />

  <ResponseField name="base_url" type="str">
    API server URL. Defaults to the Nebius Token Factory production endpoint.
  </ResponseField>

  ### Methods

  <a />

  #### `resolve()`

  ```python theme={null}
  def resolve() -> Self
  ```

  <ResponseField name="returns" type="Self" />

  <a />

  #### `get_headers()`

  ```python theme={null}
  def get_headers() -> dict[str, str]
  ```

  <ResponseField name="returns" type="dict[str, str]" />
</div>


# Clients
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/client



<a />

## `class Contree`

```python theme={null}
class contree_sdk.Contree(config, *, base_url, token)
```

Asynchronous ConTree SDK client.

<div>
  ### Attributes

  <a />

  <ResponseField name="config" type="ContreeConfig">
    [`ContreeConfig`](./config#contree_sdk.config.ContreeConfig)

    Current client configuration.
  </ResponseField>

  <a />

  <ResponseField name="files" type="FilesManager">
    [`FilesManager`](./files#contree_sdk.sdk.managers.files.FilesManager)

    Manager for file operations.
  </ResponseField>

  <a />

  <ResponseField name="images" type="ImagesManager">
    [`ImagesManager`](./images#contree_sdk.sdk.managers.images.ImagesManager)

    Manager for image operations.
  </ResponseField>

  ### Methods

  <a />

  #### `get_token_info()`

  ```python theme={null}
  async def get_token_info(refresh) -> WhoAmI
  ```

  <ParamField />

  <ResponseField name="returns" type="WhoAmI" />
</div>

<a />

## `class ContreeSync`

```python theme={null}
class contree_sdk.ContreeSync(config, *, base_url, token)
```

Synchronous ConTree SDK client.

<div>
  ### Attributes

  <a />

  <ResponseField name="config" type="ContreeConfig">
    [`ContreeConfig`](./config#contree_sdk.config.ContreeConfig)

    Current client configuration.
  </ResponseField>

  <a />

  <ResponseField name="images" type="ImagesManagerSync">
    [`ImagesManagerSync`](./images#contree_sdk.sdk.managers.images.ImagesManagerSync)

    Manager for image operations.
  </ResponseField>

  <a />

  <ResponseField name="files" type="FilesManagerSync">
    [`FilesManagerSync`](./files#contree_sdk.sdk.managers.files.FilesManagerSync)

    Manager for file operations.
  </ResponseField>

  ### Methods

  <a />

  #### `get_token_info()`

  ```python theme={null}
  def get_token_info(refresh) -> WhoAmI
  ```

  <ParamField />

  <ResponseField name="returns" type="WhoAmI" />
</div>


# ContreeConfig
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/config



<a />

## `class ContreeConfig`

```python theme={null}
class contree_sdk.config.ContreeConfig(auth, transport_timeout, file_upload_chunk_size, operation_import_timeout, operation_run_timeout, operation_timeout, default_truncate_output_at, token_expiration_warning_threshold, images_list_batch_size)
```

Configuration for the ConTree SDK client.

The `auth` field controls authentication and the target URL. String fields
on auth objects support env var lookup: if the value matches an existing
environment variable name, the value is loaded from it.

<div>
  ### Attributes

  <a />

  <ResponseField name="auth" type="IAMAuth | JWTAuth">
    [`IAMAuth`](./auth#contree_sdk.auth.IAMAuth) | [`JWTAuth`](./auth#contree_sdk.auth.JWTAuth)

    Authentication configuration. Use `IAMAuth` for Nebius IAM tokens or `JWTAuth` for legacy tokens.
  </ResponseField>

  <a />

  <ResponseField name="transport_timeout" type="float">
    HTTP timeout in seconds.
  </ResponseField>

  <a />

  <ResponseField name="file_upload_chunk_size" type="int">
    Chunk size in bytes for uploads.
  </ResponseField>

  <a />

  <ResponseField name="operation_import_timeout" type="float | None">
    Import operation timeout, falls back to operation\_timeout.
  </ResponseField>

  <a />

  <ResponseField name="operation_run_timeout" type="float | None">
    Run operation timeout, falls back to operation\_timeout.
  </ResponseField>

  <a />

  <ResponseField name="operation_timeout" type="float">
    Default timeout for operations.
  </ResponseField>

  <a />

  <ResponseField name="default_truncate_output_at" type="int">
    Default truncate output at which to truncate stdout and stderr.
  </ResponseField>

  <a />

  <ResponseField name="token_expiration_warning_threshold" type="timedelta">
    Warn if token expires within this duration.
  </ResponseField>

  <a />

  <ResponseField name="images_list_batch_size" type="int">
    Batch size for listing images.
  </ResponseField>
</div>


# Files Manager
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/files



<a />

## `class FilesManager`

```python theme={null}
class contree_sdk.sdk.managers.files.FilesManager(client)
```

<div>
  ### Methods

  <a />

  #### `upload()`

  ```python theme={null}
  async def upload(local_path) -> UploadedFile
  ```

  <ParamField />

  <ResponseField name="returns" type="UploadedFile" />
</div>

<a />

## `class FilesManagerSync`

```python theme={null}
class contree_sdk.sdk.managers.files.FilesManagerSync(client)
```

<div>
  ### Methods

  <a />

  #### `upload()`

  ```python theme={null}
  def upload(local_path) -> UploadedFile
  ```

  <ParamField />

  <ResponseField name="returns" type="UploadedFile" />
</div>


# Images
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/image



<a />

## `class ContreeImage`

```python theme={null}
class contree_sdk.sdk.objects.image.ContreeImage(client, uuid, tag)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="client" />

  <a />

  <ResponseField name="elapsed" type="timedelta">
    Time elapsed during execution.
  </ResponseField>

  <a />

  <ResponseField name="exit_code" type="int">
    Exit code of the executed command.
  </ResponseField>

  <a />

  <ResponseField name="result" type="ContreeResult">
    Execution result. Only available after successful execution.
  </ResponseField>

  <a />

  <ResponseField name="state" type="ImageState">
    Current state of the image in the execution lifecycle.
  </ResponseField>

  <a />

  <ResponseField name="stderr" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stderr output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="stdin" type="str | bytes | Path | Readable | AsyncReadable | None">
    Configured stdin source.
  </ResponseField>

  <a />

  <ResponseField name="stdout" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stdout output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="uuid" type="UUID | None">
    Unique identifier of the image.
  </ResponseField>

  <a />

  <ResponseField name="tag" type="str | None">
    Optional tag associated with the image.
  </ResponseField>

  ### Methods

  <a />

  #### `apply_files()`

  ```python theme={null}
  async def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Upload files into a new image derived from this one.

  <ParamField type="str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec]">
    Files to upload.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files as a list or a dict mapping destination paths to sources.
    When both args and files are provided, they are merged.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image with the uploaded files baked in.
  </ResponseField>

  <a />

  #### `download()`

  ```python theme={null}
  async def download(image_path, local_path) -> Path | None
  ```

  Download a file from the image to local filesystem.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ParamField type="str | Path | None">
    Local destination path. Defaults to filename from image\_path.
  </ParamField>

  <ResponseField name="returns" type="Path | None">
    Path to the downloaded file.
  </ResponseField>

  <a />

  #### `ls()`

  ```python theme={null}
  async def ls(path) -> list[ImageFile | ImageDirectory]
  ```

  List files and directories at the given path.

  <ParamField type="str | PurePosixPath">
    Path inside the image to list.
  </ParamField>

  <ResponseField name="returns" type="list[ImageFile | ImageDirectory]">
    list\[[`ImageFile`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFile) | [`ImageDirectory`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectory)]

    List of ImageFile and ImageDirectory objects.
  </ResponseField>

  <a />

  #### `read()`

  ```python theme={null}
  async def read(image_path) -> bytes
  ```

  Read file contents from the image.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ResponseField name="returns" type="bytes">
    File contents as bytes.
  </ResponseField>

  <a />

  #### `run()`

  ```python theme={null}
  def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at, preserve_env) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Prepare image for command execution.

  <ParamField type="str | None">
    Command to execute (mutually exclusive with shell).
  </ParamField>

  <ParamField type="str | None">
    Shell command string (mutually exclusive with command).
  </ParamField>

  <ParamField type="Iterable[str] | None">
    Command arguments.
  </ParamField>

  <ParamField type="dict[str, str] | None">
    Environment variables.
  </ParamField>

  <ParamField type="str | None">
    Working directory inside the image.
  </ParamField>

  <ParamField type="str | None">
    Hostname for the container.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Input source.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stdout.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stderr.
  </ParamField>

  <ParamField type="str | None">
    Tag for the resulting image.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files to upload into the image.
  </ParamField>

  <ParamField type="float | timedelta | None">
    Execution timeout in seconds or as timedelta.
  </ParamField>

  <ParamField type="bool">
    If True, image is discarded after execution.
  </ParamField>

  <ParamField type="int | None">
    number of bytes to truncate stdout and stderr. Defaults to default\_truncate\_output\_at
  </ParamField>

  <ParamField type="bool">
    If True, environment variables are preserved in resulting image after execution.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance configured for execution.
  </ResponseField>

  <ResponseField name="raises">
    **DisposableImageRunError** – If attempting to run on a disposed image.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If neither command nor shell is provided.
  </ResponseField>

  <a />

  #### `session()`

  ```python theme={null}
  def session() -> ContreeSession
  ```

  <ResponseField name="returns" type="ContreeSession">
    [`ContreeSession`](./session#contree_sdk.sdk.objects.session.ContreeSession)
  </ResponseField>

  <a />

  #### `start()`

  ```python theme={null}
  async def start() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Start the prepared command without waiting for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance in EXECUTING state; await it or iterate its
    output chunks to get the result.
  </ResponseField>

  <a />

  #### `tag_as()`

  ```python theme={null}
  async def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Tag this image with the specified tag, or remove the tag if None.

  <ParamField type="str | None">
    Tag name to apply to the image, or None to remove the tag.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with updated tag.
  </ResponseField>

  <a />

  #### `untag()`

  ```python theme={null}
  async def untag() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Remove the tag from this image.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with tag set to None.
  </ResponseField>
</div>

<a />

## `class ContreeImageSync`

```python theme={null}
class contree_sdk.sdk.objects.image.ContreeImageSync(client, uuid, tag)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="client" />

  <a />

  <ResponseField name="elapsed" type="timedelta">
    Time elapsed during execution.
  </ResponseField>

  <a />

  <ResponseField name="exit_code" type="int">
    Exit code of the executed command.
  </ResponseField>

  <a />

  <ResponseField name="result" type="ContreeResult">
    Execution result. Only available after successful execution.
  </ResponseField>

  <a />

  <ResponseField name="state" type="ImageState">
    Current state of the image in the execution lifecycle.
  </ResponseField>

  <a />

  <ResponseField name="stderr" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stderr output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="stdin" type="str | bytes | Path | Readable | AsyncReadable | None">
    Configured stdin source.
  </ResponseField>

  <a />

  <ResponseField name="stdout" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stdout output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="uuid" type="UUID | None">
    Unique identifier of the image.
  </ResponseField>

  <a />

  <ResponseField name="tag" type="str | None">
    Optional tag associated with the image.
  </ResponseField>

  ### Methods

  <a />

  #### `apply_files()`

  ```python theme={null}
  def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Upload files into a new image derived from this one.

  <ParamField type="str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec]">
    Files to upload.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files as a list or a dict mapping destination paths to sources.
    When both args and files are provided, they are merged.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image with the uploaded files baked in.
  </ResponseField>

  <a />

  #### `download()`

  ```python theme={null}
  def download(image_path, local_path) -> Path | None
  ```

  Download a file from the image to local filesystem.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ParamField type="str | Path | None">
    Local destination path. Defaults to filename from image\_path.
  </ParamField>

  <ResponseField name="returns" type="Path | None">
    Path to the downloaded file.
  </ResponseField>

  <a />

  #### `ls()`

  ```python theme={null}
  def ls(path) -> list[ImageFileSync | ImageDirectorySync]
  ```

  List files and directories at the given path.

  <ParamField type="str | PurePosixPath">
    Path inside the image to list.
  </ParamField>

  <ResponseField name="returns" type="list[ImageFileSync | ImageDirectorySync]">
    list\[[`ImageFileSync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFileSync) | [`ImageDirectorySync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectorySync)]

    List of ImageFileSync and ImageDirectorySync objects.
  </ResponseField>

  <a />

  #### `popen()`

  ```python theme={null}
  def popen(args, *, stdin, input, stdout, stderr, shell, cwd, timeout, check, text, env) -> ContreeProcessSync
  ```

  Run a command with subprocess-like interface.

  <ParamField type="list[str] | str | None">
    Command and arguments list.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Input source.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Alternative input source (alias for stdin).
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stdout.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stderr.
  </ParamField>

  <ParamField type="bool">
    If True, treat args as shell command.
  </ParamField>

  <ParamField type="str | None">
    Working directory inside the image.
  </ParamField>

  <ParamField type="float | None">
    Execution timeout in seconds.
  </ParamField>

  <ParamField type="bool">
    If True, raise on non-zero exit code.
  </ParamField>

  <ParamField type="bool | None">
    If True, decode output as text.
  </ParamField>

  <ParamField type="dict[str, str] | None">
    Environment variables.
  </ParamField>

  <ResponseField name="returns" type="ContreeProcessSync">
    [`ContreeProcessSync`](./subprocess#contree_sdk.sdk.objects.subprocess.ContreeProcessSync)

    ContreeProcessSync object with execution results.
  </ResponseField>

  <a />

  #### `read()`

  ```python theme={null}
  def read(image_path) -> bytes
  ```

  Read file contents from the image.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ResponseField name="returns" type="bytes">
    File contents as bytes.
  </ResponseField>

  <a />

  #### `run()`

  ```python theme={null}
  def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at, preserve_env) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Prepare image for command execution.

  <ParamField type="str | None">
    Command to execute (mutually exclusive with shell).
  </ParamField>

  <ParamField type="str | None">
    Shell command string (mutually exclusive with command).
  </ParamField>

  <ParamField type="Iterable[str] | None">
    Command arguments.
  </ParamField>

  <ParamField type="dict[str, str] | None">
    Environment variables.
  </ParamField>

  <ParamField type="str | None">
    Working directory inside the image.
  </ParamField>

  <ParamField type="str | None">
    Hostname for the container.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Input source.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stdout.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stderr.
  </ParamField>

  <ParamField type="str | None">
    Tag for the resulting image.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files to upload into the image.
  </ParamField>

  <ParamField type="float | timedelta | None">
    Execution timeout in seconds or as timedelta.
  </ParamField>

  <ParamField type="bool">
    If True, image is discarded after execution.
  </ParamField>

  <ParamField type="int | None">
    number of bytes to truncate stdout and stderr. Defaults to default\_truncate\_output\_at
  </ParamField>

  <ParamField type="bool">
    If True, environment variables are preserved in resulting image after execution.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance configured for execution.
  </ResponseField>

  <ResponseField name="raises">
    **DisposableImageRunError** – If attempting to run on a disposed image.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If neither command nor shell is provided.
  </ResponseField>

  <a />

  #### `session()`

  ```python theme={null}
  def session() -> ContreeSessionSync
  ```

  <ResponseField name="returns" type="ContreeSessionSync">
    [`ContreeSessionSync`](./session#contree_sdk.sdk.objects.session.ContreeSessionSync)
  </ResponseField>

  <a />

  #### `start()`

  ```python theme={null}
  def start() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Start the prepared command without waiting for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance in EXECUTING state; await it or iterate its
    output chunks to get the result.
  </ResponseField>

  <a />

  #### `tag_as()`

  ```python theme={null}
  def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Tag this image with the specified tag, or remove the tag if None.

  <ParamField type="str | None">
    Tag name to apply to the image, or None to remove the tag.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with updated tag.
  </ResponseField>

  <a />

  #### `untag()`

  ```python theme={null}
  def untag() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Remove the tag from this image.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with tag set to None.
  </ResponseField>

  <a />

  #### `wait()`

  ```python theme={null}
  def wait() -> TypeVar(_T, bound= _ImageLikeSync)
  ```

  Execute the prepared command and wait for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeSync)">
    New image instance with execution results.
  </ResponseField>
</div>


# Image files/directories
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/image_fs



<a />

## `class ImageDirectory`

```python theme={null}
class contree_sdk.sdk.objects.image_fs.ImageDirectory(size, path, uid, gid, mode, mtime, nlink, symlink_to, is_dir, is_regular, is_socket, is_fifo, is_symlink, owner, group, _image, _path)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="full_path" type="PurePosixPath" />

  <a />

  <ResponseField name="is_file" />

  <a />

  <ResponseField name="name" type="str" />

  <a />

  <ResponseField name="is_dir" type="Literal[True]" />

  <a />

  <ResponseField name="size" type="int" />

  <a />

  <ResponseField name="path" type="str" />

  <a />

  <ResponseField name="uid" type="int" />

  <a />

  <ResponseField name="gid" type="int" />

  <a />

  <ResponseField name="mode" type="int" />

  <a />

  <ResponseField name="mtime" type="int" />

  <a />

  <ResponseField name="nlink" type="int" />

  <a />

  <ResponseField name="symlink_to" type="str" />

  <a />

  <ResponseField name="is_regular" type="bool" />

  <a />

  <ResponseField name="is_socket" type="bool" />

  <a />

  <ResponseField name="is_fifo" type="bool" />

  <a />

  <ResponseField name="is_symlink" type="bool" />

  <a />

  <ResponseField name="owner" type="str" />

  <a />

  <ResponseField name="group" type="str" />

  ### Methods

  <a />

  #### `ls()`

  ```python theme={null}
  async def ls(path) -> list[ImageFile | ImageDirectory]
  ```

  <ParamField />

  <ResponseField name="returns" type="list[ImageFile | ImageDirectory]">
    list\[[`ImageFile`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFile) | [`ImageDirectory`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectory)]
  </ResponseField>
</div>

<a />

## `class ImageDirectorySync`

```python theme={null}
class contree_sdk.sdk.objects.image_fs.ImageDirectorySync(size, path, uid, gid, mode, mtime, nlink, symlink_to, is_dir, is_regular, is_socket, is_fifo, is_symlink, owner, group, _image, _path)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="full_path" type="PurePosixPath" />

  <a />

  <ResponseField name="is_file" />

  <a />

  <ResponseField name="name" type="str" />

  <a />

  <ResponseField name="is_dir" type="Literal[True]" />

  <a />

  <ResponseField name="size" type="int" />

  <a />

  <ResponseField name="path" type="str" />

  <a />

  <ResponseField name="uid" type="int" />

  <a />

  <ResponseField name="gid" type="int" />

  <a />

  <ResponseField name="mode" type="int" />

  <a />

  <ResponseField name="mtime" type="int" />

  <a />

  <ResponseField name="nlink" type="int" />

  <a />

  <ResponseField name="symlink_to" type="str" />

  <a />

  <ResponseField name="is_regular" type="bool" />

  <a />

  <ResponseField name="is_socket" type="bool" />

  <a />

  <ResponseField name="is_fifo" type="bool" />

  <a />

  <ResponseField name="is_symlink" type="bool" />

  <a />

  <ResponseField name="owner" type="str" />

  <a />

  <ResponseField name="group" type="str" />

  ### Methods

  <a />

  #### `ls()`

  ```python theme={null}
  def ls(path) -> list[ImageFileSync | ImageDirectorySync]
  ```

  <ParamField />

  <ResponseField name="returns" type="list[ImageFileSync | ImageDirectorySync]">
    list\[[`ImageFileSync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFileSync) | [`ImageDirectorySync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectorySync)]
  </ResponseField>
</div>

<a />

## `class ImageFile`

```python theme={null}
class contree_sdk.sdk.objects.image_fs.ImageFile(size, path, uid, gid, mode, mtime, nlink, symlink_to, is_dir, is_regular, is_socket, is_fifo, is_symlink, owner, group, _image, _path)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="full_path" type="PurePosixPath" />

  <a />

  <ResponseField name="is_file" />

  <a />

  <ResponseField name="name" type="str" />

  <a />

  <ResponseField name="is_dir" type="Literal[False]" />

  <a />

  <ResponseField name="size" type="int" />

  <a />

  <ResponseField name="path" type="str" />

  <a />

  <ResponseField name="uid" type="int" />

  <a />

  <ResponseField name="gid" type="int" />

  <a />

  <ResponseField name="mode" type="int" />

  <a />

  <ResponseField name="mtime" type="int" />

  <a />

  <ResponseField name="nlink" type="int" />

  <a />

  <ResponseField name="symlink_to" type="str" />

  <a />

  <ResponseField name="is_regular" type="bool" />

  <a />

  <ResponseField name="is_socket" type="bool" />

  <a />

  <ResponseField name="is_fifo" type="bool" />

  <a />

  <ResponseField name="is_symlink" type="bool" />

  <a />

  <ResponseField name="owner" type="str" />

  <a />

  <ResponseField name="group" type="str" />

  ### Methods

  <a />

  #### `download()`

  ```python theme={null}
  async def download(local_path) -> Path
  ```

  <ParamField />

  <ResponseField name="returns" type="Path" />

  <a />

  #### `read()`

  ```python theme={null}
  async def read() -> bytes
  ```

  <ResponseField name="returns" type="bytes" />
</div>

<a />

## `class ImageFileSync`

```python theme={null}
class contree_sdk.sdk.objects.image_fs.ImageFileSync(size, path, uid, gid, mode, mtime, nlink, symlink_to, is_dir, is_regular, is_socket, is_fifo, is_symlink, owner, group, _image, _path)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="full_path" type="PurePosixPath" />

  <a />

  <ResponseField name="is_file" />

  <a />

  <ResponseField name="name" type="str" />

  <a />

  <ResponseField name="is_dir" type="Literal[False]" />

  <a />

  <ResponseField name="size" type="int" />

  <a />

  <ResponseField name="path" type="str" />

  <a />

  <ResponseField name="uid" type="int" />

  <a />

  <ResponseField name="gid" type="int" />

  <a />

  <ResponseField name="mode" type="int" />

  <a />

  <ResponseField name="mtime" type="int" />

  <a />

  <ResponseField name="nlink" type="int" />

  <a />

  <ResponseField name="symlink_to" type="str" />

  <a />

  <ResponseField name="is_regular" type="bool" />

  <a />

  <ResponseField name="is_socket" type="bool" />

  <a />

  <ResponseField name="is_fifo" type="bool" />

  <a />

  <ResponseField name="is_symlink" type="bool" />

  <a />

  <ResponseField name="owner" type="str" />

  <a />

  <ResponseField name="group" type="str" />

  ### Methods

  <a />

  #### `download()`

  ```python theme={null}
  def download(local_path) -> Path
  ```

  <ParamField />

  <ResponseField name="returns" type="Path" />

  <a />

  #### `read()`

  ```python theme={null}
  def read() -> bytes
  ```

  <ResponseField name="returns" type="bytes" />
</div>


# Images Manager
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/images



<a />

## `class ImagesManager`

```python theme={null}
class contree_sdk.sdk.managers.images.ImagesManager(client)
```

<div>
  ### Methods

  <a />

  #### `__aiter__()`

  ```python theme={null}
  async def __aiter__()
  ```

  <a />

  #### `__call__()`

  ```python theme={null}
  async def __call__(number, kind, tagged, since, until) -> list[TypeVar(_ImageT, bound= _ContreeImageBase)]
  ```

  Fetch a list of images with optional filters.

  <ParamField type="int | None">
    Maximum number of images to return. None returns all.
  </ParamField>

  <ParamField type="ImageKind | None">
    Filter by image kind.
  </ParamField>

  <ParamField type="bool">
    If True, return only tagged images.
  </ParamField>

  <ParamField type="datetime | timedelta | None">
    Return images created after this time. Accepts datetime or timedelta relative to now.
  </ParamField>

  <ParamField type="datetime | timedelta | None">
    Return images created before this time. Accepts datetime or timedelta relative to now.
  </ParamField>

  <ResponseField name="returns" type="list[TypeVar(_ImageT, bound= _ContreeImageBase)]">
    List of images matching the given filters.
  </ResponseField>

  <a />

  #### `docker()`

  ```python theme={null}
  async def docker(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `import_from()`

  ```python theme={null}
  async def import_from(image, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Import an image from an external registry into Contree.

  <ParamField type="str | OCIReference">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference)

    OCI reference string or OCIReference pointing to the source image.
  </ParamField>

  <ParamField type="str | None">
    Tag to assign to the imported image. Defaults to the tag in the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for private registries.
  </ParamField>

  <ParamField type="str | None">
    Registry password for private registries.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If image is a UUID or credentials are incomplete.
  </ResponseField>

  <ResponseField name="raises">
    **FailedOperationError** – If the import operation completes without returning an image.
  </ResponseField>

  <a />

  #### `oci()`

  ```python theme={null}
  async def oci(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `podman()`

  ```python theme={null}
  async def podman(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `pull()`

  ```python theme={null}
  async def pull(url_or_tag_or_uuid, *, new_tag, username, password, timeout) -> ContreeImage
  ```

  <ParamField />

  <ParamField />

  <ParamField />

  <ParamField />

  <ParamField />

  <ResponseField name="returns" type="ContreeImage">
    [`ContreeImage`](./image#contree_sdk.sdk.objects.image.ContreeImage)
  </ResponseField>

  <a />

  #### `pull_by_oci()`

  ```python theme={null}
  async def pull_by_oci(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `use()`

  ```python theme={null}
  async def use(ref, strict) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve a reference to an image object without importing.

  <ParamField type="str | UUID | OCIReference">
    str | UUID | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference)

    Image identifier — UUID, OCI reference string, or OCIReference object.
  </ParamField>

  <ParamField type="bool">
    If True, verify the image exists by fetching it from the API.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Image object corresponding to the given reference.
  </ResponseField>
</div>

<a />

## `class ImagesManagerSync`

```python theme={null}
class contree_sdk.sdk.managers.images.ImagesManagerSync(client)
```

<div>
  ### Methods

  <a />

  #### `__call__()`

  ```python theme={null}
  def __call__(number, kind, tagged, since, until) -> list[TypeVar(_ImageT, bound= _ContreeImageBase)]
  ```

  Fetch a list of images with optional filters.

  <ParamField type="int | None">
    Maximum number of images to return. None returns all.
  </ParamField>

  <ParamField type="ImageKind | None">
    Filter by image kind.
  </ParamField>

  <ParamField type="bool">
    If True, return only tagged images.
  </ParamField>

  <ParamField type="datetime | timedelta | None">
    Return images created after this time. Accepts datetime or timedelta relative to now.
  </ParamField>

  <ParamField type="datetime | timedelta | None">
    Return images created before this time. Accepts datetime or timedelta relative to now.
  </ParamField>

  <ResponseField name="returns" type="list[TypeVar(_ImageT, bound= _ContreeImageBase)]">
    List of images matching the given filters.
  </ResponseField>

  <a />

  #### `__iter__()`

  ```python theme={null}
  def __iter__()
  ```

  <a />

  #### `docker()`

  ```python theme={null}
  def docker(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `import_from()`

  ```python theme={null}
  def import_from(image, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Import an image from an external registry into Contree.

  <ParamField type="str | OCIReference">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference)

    OCI reference string or OCIReference pointing to the source image.
  </ParamField>

  <ParamField type="str | None">
    Tag to assign to the imported image. Defaults to the tag in the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for private registries.
  </ParamField>

  <ParamField type="str | None">
    Registry password for private registries.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If image is a UUID or credentials are incomplete.
  </ResponseField>

  <ResponseField name="raises">
    **FailedOperationError** – If the import operation completes without returning an image.
  </ResponseField>

  <a />

  #### `oci()`

  ```python theme={null}
  def oci(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `podman()`

  ```python theme={null}
  def podman(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `pull()`

  ```python theme={null}
  def pull(url_or_tag_or_uuid, *, new_tag, username, password, timeout) -> ContreeImageSync
  ```

  <ParamField />

  <ParamField />

  <ParamField />

  <ParamField />

  <ParamField />

  <ResponseField name="returns" type="ContreeImageSync">
    [`ContreeImageSync`](./image#contree_sdk.sdk.objects.image.ContreeImageSync)
  </ResponseField>

  <a />

  #### `pull_by_oci()`

  ```python theme={null}
  def pull_by_oci(ref, *, tag, username, password, timeout) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve an image by tag, falling back to import if not found.

  Derives the target tag from the `tag` parameter or from the reference itself,
  then tries to find an existing image with that tag. If the image does not exist,
  triggers an import and returns the result.

  <ParamField type="str | OCIReference | UUID">
    str | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference) | UUID

    UUID, OCI reference string, or OCIReference of the image.
  </ParamField>

  <ParamField type="str | None">
    Tag override; if provided, replaces the tag from the reference.
  </ParamField>

  <ParamField type="str | None">
    Registry username for authenticated imports.
  </ParamField>

  <ParamField type="str | None">
    Registry password for authenticated imports.
  </ParamField>

  <ParamField type="float | None">
    Maximum seconds to wait for the import operation.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Resolved or imported image object.
  </ResponseField>

  <ResponseField name="raises">
    **NotFoundError** – If ref is a UUID and the image does not exist.
  </ResponseField>

  <a />

  #### `use()`

  ```python theme={null}
  def use(ref, strict) -> TypeVar(_ImageT, bound= _ContreeImageBase)
  ```

  Resolve a reference to an image object without importing.

  <ParamField type="str | UUID | OCIReference">
    str | UUID | [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference)

    Image identifier — UUID, OCI reference string, or OCIReference object.
  </ParamField>

  <ParamField type="bool">
    If True, verify the image exists by fetching it from the API.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_ImageT, bound= _ContreeImageBase)">
    Image object corresponding to the given reference.
  </ResponseField>
</div>


# API Reference
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/index



Complete API reference for ConTree SDK.

## Core Components

<Columns>
  <Card title="Clients" href="./client" icon="rocket" />

  <Card title="Images Manager" href="./images" icon="layer-group" />

  <Card title="Files Manager" href="./files" icon="folder-open" />

  <Card title="Images" href="./image" icon="cube" />

  <Card title="Sessions" href="./session" icon="clock" />

  <Card title="Image files/directories" href="./image_fs" icon="folder-tree" />

  <Card title="subprocess" href="./subprocess" icon="terminal" />

  <Card title="ContreeConfig" href="./config" icon="gear" />

  <Card title="Auth" href="./auth" icon="key" />

  <Card title="OCIReference" href="./oci" icon="cloud-arrow-down" />
</Columns>


# OCIReference
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/oci



<a />

## `class OCIReference`

```python theme={null}
class contree_sdk.utils.oci.OCIReference(url, tag)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="url" type="str" />

  <a />

  <ResponseField name="tag" type="str" />

  ### Methods

  <a />

  #### `from_oci()`

  ```python theme={null}
  @classmethod
  def from_oci(ref) -> OCIReference
  ```

  <ParamField />

  <ResponseField name="returns" type="OCIReference">
    [`OCIReference`](./oci#contree_sdk.utils.oci.OCIReference)
  </ResponseField>
</div>


# Sessions
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/session



<a />

## `class ContreeSession`

```python theme={null}
class contree_sdk.sdk.objects.session.ContreeSession(image)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="client" />

  <a />

  <ResponseField name="elapsed" type="timedelta">
    Time elapsed during execution.
  </ResponseField>

  <a />

  <ResponseField name="exit_code" type="int">
    Exit code of the executed command.
  </ResponseField>

  <a />

  <ResponseField name="result" type="ContreeResult">
    Execution result. Only available after successful execution.
  </ResponseField>

  <a />

  <ResponseField name="state" type="ImageState">
    Current state of the image in the execution lifecycle.
  </ResponseField>

  <a />

  <ResponseField name="stderr" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stderr output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="stdin" type="str | bytes | Path | Readable | AsyncReadable | None">
    Configured stdin source.
  </ResponseField>

  <a />

  <ResponseField name="stdout" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stdout output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="uuid" type="UUID | None">
    Unique identifier of the image.
  </ResponseField>

  <a />

  <ResponseField name="tag" type="str | None">
    Optional tag associated with the image.
  </ResponseField>

  ### Methods

  <a />

  #### `apply_files()`

  ```python theme={null}
  async def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Upload files into a new image derived from this one.

  <ParamField type="str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec]">
    Files to upload.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files as a list or a dict mapping destination paths to sources.
    When both args and files are provided, they are merged.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image with the uploaded files baked in.
  </ResponseField>

  <a />

  #### `download()`

  ```python theme={null}
  async def download(image_path, local_path) -> Path | None
  ```

  Download a file from the image to local filesystem.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ParamField type="str | Path | None">
    Local destination path. Defaults to filename from image\_path.
  </ParamField>

  <ResponseField name="returns" type="Path | None">
    Path to the downloaded file.
  </ResponseField>

  <a />

  #### `ls()`

  ```python theme={null}
  async def ls(path) -> list[ImageFile | ImageDirectory]
  ```

  List files and directories at the given path.

  <ParamField type="str | PurePosixPath">
    Path inside the image to list.
  </ParamField>

  <ResponseField name="returns" type="list[ImageFile | ImageDirectory]">
    list\[[`ImageFile`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFile) | [`ImageDirectory`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectory)]

    List of ImageFile and ImageDirectory objects.
  </ResponseField>

  <a />

  #### `read()`

  ```python theme={null}
  async def read(image_path) -> bytes
  ```

  Read file contents from the image.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ResponseField name="returns" type="bytes">
    File contents as bytes.
  </ResponseField>

  <a />

  #### `run()`

  ```python theme={null}
  def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at, preserve_env) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Prepare image for command execution.

  <ParamField type="str | None">
    Command to execute (mutually exclusive with shell).
  </ParamField>

  <ParamField type="str | None">
    Shell command string (mutually exclusive with command).
  </ParamField>

  <ParamField type="Iterable[str] | None">
    Command arguments.
  </ParamField>

  <ParamField type="dict[str, str] | None">
    Environment variables.
  </ParamField>

  <ParamField type="str | None">
    Working directory inside the image.
  </ParamField>

  <ParamField type="str | None">
    Hostname for the container.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Input source.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stdout.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stderr.
  </ParamField>

  <ParamField type="str | None">
    Tag for the resulting image.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files to upload into the image.
  </ParamField>

  <ParamField type="float | timedelta | None">
    Execution timeout in seconds or as timedelta.
  </ParamField>

  <ParamField type="bool">
    If True, image is discarded after execution.
  </ParamField>

  <ParamField type="int | None">
    number of bytes to truncate stdout and stderr. Defaults to default\_truncate\_output\_at
  </ParamField>

  <ParamField type="bool">
    If True, environment variables are preserved in resulting image after execution.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance configured for execution.
  </ResponseField>

  <ResponseField name="raises">
    **DisposableImageRunError** – If attempting to run on a disposed image.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If neither command nor shell is provided.
  </ResponseField>

  <a />

  #### `start()`

  ```python theme={null}
  async def start() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Start the prepared command without waiting for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance in EXECUTING state; await it or iterate its
    output chunks to get the result.
  </ResponseField>

  <a />

  #### `tag_as()`

  ```python theme={null}
  async def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Tag this image with the specified tag, or remove the tag if None.

  <ParamField type="str | None">
    Tag name to apply to the image, or None to remove the tag.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with updated tag.
  </ResponseField>

  <a />

  #### `untag()`

  ```python theme={null}
  async def untag() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Remove the tag from this image.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with tag set to None.
  </ResponseField>
</div>

<a />

## `class ContreeSessionSync`

```python theme={null}
class contree_sdk.sdk.objects.session.ContreeSessionSync(image)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="client" />

  <a />

  <ResponseField name="elapsed" type="timedelta">
    Time elapsed during execution.
  </ResponseField>

  <a />

  <ResponseField name="exit_code" type="int">
    Exit code of the executed command.
  </ResponseField>

  <a />

  <ResponseField name="result" type="ContreeResult">
    Execution result. Only available after successful execution.
  </ResponseField>

  <a />

  <ResponseField name="state" type="ImageState">
    Current state of the image in the execution lifecycle.
  </ResponseField>

  <a />

  <ResponseField name="stderr" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stderr output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="stdin" type="str | bytes | Path | Readable | AsyncReadable | None">
    Configured stdin source.
  </ResponseField>

  <a />

  <ResponseField name="stdout" type="str | bytes | Path | Writable | AsyncWritable | None">
    Stdout output from the execution.
  </ResponseField>

  <a />

  <ResponseField name="uuid" type="UUID | None">
    Unique identifier of the image.
  </ResponseField>

  <a />

  <ResponseField name="tag" type="str | None">
    Optional tag associated with the image.
  </ResponseField>

  ### Methods

  <a />

  #### `apply_files()`

  ```python theme={null}
  def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Upload files into a new image derived from this one.

  <ParamField type="str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec]">
    Files to upload.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files as a list or a dict mapping destination paths to sources.
    When both args and files are provided, they are merged.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image with the uploaded files baked in.
  </ResponseField>

  <a />

  #### `download()`

  ```python theme={null}
  def download(image_path, local_path) -> Path | None
  ```

  Download a file from the image to local filesystem.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ParamField type="str | Path | None">
    Local destination path. Defaults to filename from image\_path.
  </ParamField>

  <ResponseField name="returns" type="Path | None">
    Path to the downloaded file.
  </ResponseField>

  <a />

  #### `ls()`

  ```python theme={null}
  def ls(path) -> list[ImageFileSync | ImageDirectorySync]
  ```

  List files and directories at the given path.

  <ParamField type="str | PurePosixPath">
    Path inside the image to list.
  </ParamField>

  <ResponseField name="returns" type="list[ImageFileSync | ImageDirectorySync]">
    list\[[`ImageFileSync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFileSync) | [`ImageDirectorySync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectorySync)]

    List of ImageFileSync and ImageDirectorySync objects.
  </ResponseField>

  <a />

  #### `popen()`

  ```python theme={null}
  def popen(args, *, stdin, input, stdout, stderr, shell, cwd, timeout, check, text, env) -> ContreeProcessSync
  ```

  Run a command with subprocess-like interface.

  <ParamField type="list[str] | str | None">
    Command and arguments list.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Input source.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Alternative input source (alias for stdin).
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stdout.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stderr.
  </ParamField>

  <ParamField type="bool">
    If True, treat args as shell command.
  </ParamField>

  <ParamField type="str | None">
    Working directory inside the image.
  </ParamField>

  <ParamField type="float | None">
    Execution timeout in seconds.
  </ParamField>

  <ParamField type="bool">
    If True, raise on non-zero exit code.
  </ParamField>

  <ParamField type="bool | None">
    If True, decode output as text.
  </ParamField>

  <ParamField type="dict[str, str] | None">
    Environment variables.
  </ParamField>

  <ResponseField name="returns" type="ContreeProcessSync">
    [`ContreeProcessSync`](./subprocess#contree_sdk.sdk.objects.subprocess.ContreeProcessSync)

    ContreeProcessSync object with execution results.
  </ResponseField>

  <a />

  #### `read()`

  ```python theme={null}
  def read(image_path) -> bytes
  ```

  Read file contents from the image.

  <ParamField type="str | PurePosixPath">
    Path to the file inside the image.
  </ParamField>

  <ResponseField name="returns" type="bytes">
    File contents as bytes.
  </ResponseField>

  <a />

  #### `run()`

  ```python theme={null}
  def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at, preserve_env) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Prepare image for command execution.

  <ParamField type="str | None">
    Command to execute (mutually exclusive with shell).
  </ParamField>

  <ParamField type="str | None">
    Shell command string (mutually exclusive with command).
  </ParamField>

  <ParamField type="Iterable[str] | None">
    Command arguments.
  </ParamField>

  <ParamField type="dict[str, str] | None">
    Environment variables.
  </ParamField>

  <ParamField type="str | None">
    Working directory inside the image.
  </ParamField>

  <ParamField type="str | None">
    Hostname for the container.
  </ParamField>

  <ParamField type="str | bytes | Path | Readable | AsyncReadable | None">
    Input source.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stdout.
  </ParamField>

  <ParamField type="str | Path | Writable | AsyncWritable | Literal[-1] | type[str | bytes] | None">
    Output destination for stderr.
  </ParamField>

  <ParamField type="str | None">
    Tag for the resulting image.
  </ParamField>

  <ParamField type="list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None">
    Files to upload into the image.
  </ParamField>

  <ParamField type="float | timedelta | None">
    Execution timeout in seconds or as timedelta.
  </ParamField>

  <ParamField type="bool">
    If True, image is discarded after execution.
  </ParamField>

  <ParamField type="int | None">
    number of bytes to truncate stdout and stderr. Defaults to default\_truncate\_output\_at
  </ParamField>

  <ParamField type="bool">
    If True, environment variables are preserved in resulting image after execution.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance configured for execution.
  </ResponseField>

  <ResponseField name="raises">
    **DisposableImageRunError** – If attempting to run on a disposed image.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If neither command nor shell is provided.
  </ResponseField>

  <a />

  #### `start()`

  ```python theme={null}
  def start() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Start the prepared command without waiting for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance in EXECUTING state; await it or iterate its
    output chunks to get the result.
  </ResponseField>

  <a />

  #### `tag_as()`

  ```python theme={null}
  def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Tag this image with the specified tag, or remove the tag if None.

  <ParamField type="str | None">
    Tag name to apply to the image, or None to remove the tag.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with updated tag.
  </ResponseField>

  <a />

  #### `untag()`

  ```python theme={null}
  def untag() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Remove the tag from this image.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with tag set to None.
  </ResponseField>

  <a />

  #### `wait()`

  ```python theme={null}
  def wait() -> TypeVar(_T, bound= _ImageLikeSync)
  ```

  Execute the prepared command and wait for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeSync)">
    New image instance with execution results.
  </ResponseField>
</div>


# subprocess
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/subprocess



<a />

## `class ContreeProcessSync`

```python theme={null}
class contree_sdk.sdk.objects.subprocess.ContreeProcessSync(image, check)
```

<div>
  ### Attributes

  <a />

  <ResponseField name="returncode" type="int" />

  <a />

  <ResponseField name="stderr" type="str | bytes | Path | Writable | AsyncWritable | None" />

  <a />

  <ResponseField name="stdin" type="str | bytes | Path | Readable | AsyncReadable | None" />

  <a />

  <ResponseField name="stdout" type="str | bytes | Path | Writable | AsyncWritable | None" />

  ### Methods

  <a />

  #### `communicate()`

  ```python theme={null}
  def communicate(input, timeout)
  ```

  <a />

  #### `wait()`

  ```python theme={null}
  def wait() -> None
  ```

  <ResponseField name="returns" type="None" />
</div>


# Running Commands
Source: https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/running-commands



ConTree SDK provides multiple ways to execute commands in containers, from simple shell commands to complex workflows with file handling and custom I/O.

## Basic Command Execution

You can run commands using shell syntax or by specifying command and arguments separately:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("busybox:latest")
    print(f"Using {image=}")

    result = await image.run(shell="echo 'Hello World'")
    print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    result = await image.run(shell="pwd")
    print(f"Current directory: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="ls -la")
    print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="cat -", stdin="Hello from stdin\n")
    print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

    result = await image.run(shell="echo 'Error message' >&2; exit 1")
    print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```

    See [`ContreeImage.run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.run) and [`ContreeSession.run()`](./reference/session#contree_sdk.sdk.objects.session.ContreeSession.run) for all options.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("busybox:latest")
    print(f"Using {image=}")

    result = image.run(shell="echo 'Hello World'").wait()
    print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    result = image.run(shell="pwd").wait()
    print(f"Current directory: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="ls -la").wait()
    print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="cat -", stdin="Hello from stdin\n").wait()
    print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

    result = image.run(shell="echo 'Error message' >&2; exit 1").wait()
    print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```

    See [`ContreeImageSync.run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.run) and [`ContreeSessionSync.run()`](./reference/session#contree_sdk.sdk.objects.session.ContreeSessionSync.run) for all options.
  </Tab>
</Tabs>

## Command Execution Mode

You can execute commands by specifying the executable path and arguments separately:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("alpine:3.20", strict=True)
    print(f"Pulled {image=}")

    print("\nExample 1: Simple command execution")
    result = await image.run("/bin/echo", args=["Hello from command parameter!"])
    print(f"Result: {result.stdout=}, {result.exit_code=}")

    print("\nExample 2: Command with arguments")
    result = await image.run("/bin/ls", args=["-la", "/tmp"])
    print(f"Result: {result.stdout=}, {result.exit_code=}")

    print("\nExample 3: Command with environment variables")
    result = await image.run("/bin/printenv", args=["MY_VAR"], env={"MY_VAR": "test_value"})
    print(f"Result: {result.stdout=}, {result.exit_code=}")

    print("\nExample 4: Preserve environment variables in the resulting image")
    prepared = await image.run(
        shell="true",
        env={"MY_PERSISTED_VAR": "persisted_value"},
        preserve_env=True,
        disposable=False,
    )
    result = await prepared.run("/bin/printenv", args=["MY_PERSISTED_VAR"])
    print(f"Result: {result.stdout=}, {result.exit_code=}")
    ```

    See [`ContreeImage.run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.run) and [`ContreeSession.run()`](./reference/session#contree_sdk.sdk.objects.session.ContreeSession.run) for command execution details.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("alpine:3.20", strict=True)
    print(f"Pulled {image=}")

    print("\nExample 1: Simple command execution")
    result = image.run("/bin/echo", args=["Hello from command parameter!"]).wait()
    print(f"Result: {result.stdout=}, {result.exit_code=}")

    print("\nExample 2: Command with arguments")
    result = image.run("/bin/ls", args=["-la", "/tmp"]).wait()
    print(f"Result: {result.stdout=}, {result.exit_code=}")

    print("\nExample 3: Command with environment variables")
    result = image.run("/bin/printenv", args=["MY_VAR"], env={"MY_VAR": "test_value"}).wait()
    print(f"Result: {result.stdout=}, {result.exit_code=}")

    print("\nExample 4: Preserve environment variables in the resulting image")
    prepared = image.run(
        shell="true",
        env={"MY_PERSISTED_VAR": "persisted_value"},
        preserve_env=True,
        disposable=False,
    ).wait()
    result = prepared.run("/bin/printenv", args=["MY_PERSISTED_VAR"]).wait()
    print(f"Result: {result.stdout=}, {result.exit_code=}")
    ```

    See [`ContreeImageSync.run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.run) and [`ContreeSessionSync.run()`](./reference/session#contree_sdk.sdk.objects.session.ContreeSessionSync.run) for command execution details.
  </Tab>
</Tabs>

### Command vs Shell Mode

* **Command mode**: Use `command="/bin/ls"` with `args=["-la", "/tmp"]` for direct execution without shell interpretation
* **Shell mode**: Use `shell="ls -la /tmp"` for shell commands with pipes, redirects, and wildcards
* **Environment variables**: Pass `env={"VAR": "value"}` to set environment for command execution

### Preserving Environment Variables

By default, values passed through `env` are available only to the current command. Set `preserve_env=True`
with `disposable=False` when those variables should be written into the resulting image and inherited by
later commands:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    prepared = await image.run(
        shell="true",
        env={"MY_PERSISTED_VAR": "persisted_value"},
        preserve_env=True,
        disposable=False,
    )
    result = await prepared.run("/bin/printenv", args=["MY_PERSISTED_VAR"])
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    prepared = image.run(
        shell="true",
        env={"MY_PERSISTED_VAR": "persisted_value"},
        preserve_env=True,
        disposable=False,
    ).wait()
    result = prepared.run("/bin/printenv", args=["MY_PERSISTED_VAR"]).wait()
    ```
  </Tab>
</Tabs>

On the ConTree side, `preserve_env=True` merges the image’s existing `metadata/env` entries with the `env`
values from the request, with request values taking priority, then writes the merged values back to
`metadata/env` in the resulting image. Setting a variable to an empty string removes it from the preserved
environment.

## Working with Files

You can upload and use files in your commands by specifying local file paths or pre-uploaded file objects:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("busybox:latest")
    print(f"Using {image=}")

    print("\nExample 1: Local file upload to image")
    with NamedTemporaryFile(mode="w", suffix=".txt") as test_file:
        test_file.write("some txt file\nsecond line\n\nlast line\n")
        test_file.flush()

        result = await image.run(shell=f"cat /{test_file.name.split('/')[-1]} | grep line", files=[test_file.name])
        print(f"Run with local file: {result.stdout=}, {result.exit_code=}")

    print("\nExample 2: Upload file via contree.files and use in image")
    with NamedTemporaryFile(mode="w", suffix=".sh") as script_file:
        script_file.write("#!/bin/sh\necho 'Hello from uploaded script'\necho 'Working directory:'\npwd\n")
        script_file.flush()

        uploaded_file = await client.files.upload(script_file.name)
        print(f"Uploaded file: {uploaded_file=}")

        result = await image.run(shell="sh /file.sh", files={"file.sh": uploaded_file})
        print(f"Run with uploaded file: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    print("\nExample 3: Bake files into a new image with apply_files")
    with NamedTemporaryFile(mode="w", suffix=".txt") as f:
        f.write("hello from baked file\n")
        f.flush()
        baked = await image.apply_files({"baked.txt": f.name})
        result = await baked.run(shell="cat /baked.txt")
        print(f"File is present in new image: {result.stdout=}")

    print("\nExample 4: Multiple files working together")
    with (
        NamedTemporaryFile(mode="w", suffix=".txt") as data_file,
        NamedTemporaryFile(mode="w", suffix=".sh") as script_file,
    ):
        data_file.write("apple\nbanana\ncherry\ndate\n")
        data_file.flush()

        script_file.write(
            "#!/bin/bash\necho 'Processing data:'\ncat /data.txt | grep -E '^[ab]'"
            "\necho 'Found items starting with a or b'"
        )
        script_file.flush()

        result = await image.run(
            shell="chmod +x /script.sh && sh /script.sh",
            files={"data.txt": data_file.name, "script.sh": script_file.name},
        )
        print(f"Multiple files result: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("busybox:latest")
    print(f"Using {image=}")

    print("\nExample 1: Local file upload to image")
    with NamedTemporaryFile(mode="w", suffix=".txt") as test_file:
        test_file.write("some txt file\nsecond line\n\nlast line\n")
        test_file.flush()

        result = image.run(shell=f"cat /{test_file.name.split('/')[-1]} | grep line", files=[test_file.name]).wait()
        print(f"Run with local file: {result.stdout=}, {result.exit_code=}")

    print("\nExample 2: Upload file via contree.files and use in image")
    with NamedTemporaryFile(mode="w", suffix=".sh") as script_file:
        script_file.write("#!/bin/sh\necho 'Hello from uploaded script'\necho 'Working directory:'\npwd\n")
        script_file.flush()

        uploaded_file = client.files.upload(script_file.name)
        print(f"Uploaded file: {uploaded_file=}")

        result = image.run(shell="sh /file.sh", files={"file.sh": uploaded_file}).wait()
        print(f"Run with uploaded file: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

    print("\nExample 3: Bake files into a new image with apply_files")
    with NamedTemporaryFile(mode="w", suffix=".txt") as f:
        f.write("hello from baked file\n")
        f.flush()
        baked = image.apply_files({"baked.txt": f.name})
        result = baked.run(shell="cat /baked.txt").wait()
        print(f"File is present in new image: {result.stdout=}")

    print("\nExample 4: Multiple files working together")
    with (
        NamedTemporaryFile(mode="w", suffix=".txt") as data_file,
        NamedTemporaryFile(mode="w", suffix=".sh") as script_file,
    ):
        data_file.write("apple\nbanana\ncherry\ndate\n")
        data_file.flush()

        script_file.write(
            "#!/bin/bash\necho 'Processing data:'\ncat /data.txt | grep -E '^[ab]'"
            "\necho 'Found items starting with a or b'"
        )
        script_file.flush()

        result = image.run(
            shell="chmod +x /script.sh && sh /script.sh",
            files={"data.txt": data_file.name, "script.sh": script_file.name},
        ).wait()
        print(f"Multiple files result: {result.stdout=}, {result.stderr=}, {result.exit_code=}")
    ```
  </Tab>
</Tabs>

### File Upload Methods

You can provide files to commands in several ways:

* **Local file paths**: `files=["/path/to/local/file.txt"]` - Upload files directly
* **File mapping**: `files={"dest.txt": "/local/source.txt"}` - Upload with custom names
* **Pre-uploaded files**: `files={"script.sh": uploaded_file_object}` - Use files uploaded via `client.files.upload()`

## Advanced I/O Handling

You can use Python I/O objects for more sophisticated input/output handling:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await client.images.use("busybox:latest")
    print(f"Using {image=}")

    print("\nExample 1: StringIO for stdin and stdout")
    stdin_io = StringIO("apple\nbanana\ncherry\ndate\n")
    stdout_io = StringIO()

    result = await image.run(shell="grep 'a' | sort", stdin=stdin_io, stdout=stdout_io)
    print(f"StringIO result: exit_code={result.exit_code}")
    print(f"Output in StringIO: {stdout_io.getvalue()=}")
    print(f"result.stdout is the StringIO object: {result.stdout is stdout_io}")

    print("\nExample 2: PIPE for stderr capture")
    result = await image.run(shell="echo 'to stdout'; echo 'to stderr' >&2; exit 0", stderr=PIPE)
    print(f"PIPE stderr: {result.stdout=}")
    print(f"Stderr content: {result.stderr.read().decode()=}")
    print(f"Stderr type: {type(result.stderr).__name__}")

    print("\nExample 3: Output to bytes")
    result = await image.run(shell="echo 'Hello bytes world'", stdout=bytes)
    print(f"Bytes output: {result.stdout=}")
    print(f"Output type: {type(result.stdout).__name__}")

    print("\nExample 4: open() file object for input")
    with NamedTemporaryFile(mode="w", suffix=".txt") as temp_file:
        temp_file.write("line1\nline2\nline3\n")
        temp_file.flush()

        with open(temp_file.name) as file_obj:
            result = await image.run(shell="wc -l", stdin=file_obj)
            print(f"File object input: {result.stdout=}, {result.exit_code=}")

    print("\nExample 5: BytesIO for binary data")
    binary_data = BytesIO(b"binary\ndata\nlines\n")

    result = await image.run(shell="wc -l", stdin=binary_data)
    print(f"BytesIO input: {result.stdout=}, {result.exit_code=}")
    ```

    See [`run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.run) for I/O parameter details.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("busybox:latest")
    print(f"Using {image=}")

    print("\nExample 1: StringIO for stdin and stdout")
    stdin_io = StringIO("apple\nbanana\ncherry\ndate\n")
    stdout_io = StringIO()

    result = image.run(shell="grep 'a' | sort", stdin=stdin_io, stdout=stdout_io).wait()
    print(f"StringIO result: exit_code={result.exit_code}")
    print(f"Output in StringIO: {stdout_io.getvalue()=}")
    print(f"result.stdout is the StringIO object: {result.stdout is stdout_io}")

    print("\nExample 2: PIPE for stderr capture")
    result = image.run(shell="echo 'to stdout'; echo 'to stderr' >&2; exit 0", stderr=PIPE).wait()
    print(f"PIPE stderr: {result.stdout=}")
    print(f"Stderr content: {result.stderr.read().decode()=}")
    print(f"Stderr type: {type(result.stderr).__name__}")

    print("\nExample 3: Output to bytes")
    result = image.run(shell="echo 'Hello bytes world'", stdout=bytes).wait()
    print(f"Bytes output: {result.stdout=}")
    print(f"Output type: {type(result.stdout).__name__}")

    print("\nExample 4: open() file object for input")
    with NamedTemporaryFile(mode="w", suffix=".txt") as temp_file:
        temp_file.write("line1\nline2\nline3\n")
        temp_file.flush()

        with open(temp_file.name) as file_obj:
            result = image.run(shell="wc -l", stdin=file_obj).wait()
            print(f"File object input: {result.stdout=}, {result.exit_code=}")

    print("\nExample 5: BytesIO for binary data")
    binary_data = BytesIO(b"binary\ndata\nlines\n")

    result = image.run(shell="wc -l", stdin=binary_data).wait()
    print(f"BytesIO input: {result.stdout=}, {result.exit_code=}")
    ```

    See [`run()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.run) for I/O parameter details.
  </Tab>
</Tabs>

### Supported I/O Types

* **StringIO**: For text-based input/output
* **BytesIO**: For binary data handling
* **File objects**: Use `open()` file handles directly
* **PIPE**: Capture stderr/stdout as byte streams
* **bytes type**: Get output as bytes instead of strings

## Subprocess-like Interface (Sync Only)

You can use a subprocess-like interface for more control over process execution:

```python theme={null}
image = client.images.use("busybox:latest")
print(f"Using {image=}")

print("\nExample 1: Basic popen with wait()")
process = image.popen(["/bin/ls", "-la"], cwd="/bin")
process.wait()
print(f"Process completed: returncode={process.returncode}")
print(f"Output: {process.stdout[:100]}...")

print("\nExample 2: Shell command with stdout and stderr")
process = image.popen("echo 'Hello stdout' && echo 'Hello stderr' >&2", shell=True)
process.wait()
print(f"Stdout: {process.stdout=}")
print(f"Stderr: {process.stderr=}")

print("\nExample 3: Using communicate() for input/output")
process = image.popen(["/bin/grep", "apple"])
stdout, stderr = process.communicate(input="apple\nbanana\ncherry\napple pie\n")
print(f"Grep results: {stdout=}")
print(f"Return code: {process.returncode=}")

print("\nExample 4: Environment variables")
process = image.popen(
    "echo $MY_VAR && echo $ANOTHER_VAR", shell=True, env={"MY_VAR": "hello_world", "ANOTHER_VAR": "test_value"}
)
process.wait()
print(f"Environment output: {process.stdout=}")

print("\nExample 5: Error handling")
process = image.popen(["/bin/ls", "/nonexistent"])
process.wait()
print(f"Error case: returncode={process.returncode}")
print(f"Error output: {process.stderr=}")
```

See [`ContreeProcessSync`](./reference/subprocess#contree_sdk.sdk.objects.subprocess.ContreeProcessSync) for the full subprocess API.

### Popen Features

* **Process control**: Use `wait()`, `communicate()`, and check `returncode`
* **Environment variables**: Pass custom `env` dictionary
* **Working directory**: Set `cwd` parameter
* **Shell commands**: Enable with `shell=True`
* **Error handling**: Check `returncode` and `stderr` for failures

## Command Parameters

### Core Parameters

* **`shell`**: Execute as shell command (e.g., `"ls -la | grep txt"`)
* **`command`**: Executable path (e.g., `"/bin/ls"`)
* **`args`**: Command arguments as tuple (e.g., `("-la", "/tmp")`)
* **`stdin`**: Input data (string, bytes, or I/O object)
* **`env`**: Environment variables as dictionary

### I/O Parameters

* **`stdout`**: Redirect stdout (StringIO, BytesIO, file path, or `bytes`)
* **`stderr`**: Redirect stderr (StringIO, BytesIO, PIPE, or `bytes`)
* **`files`**: Upload files (list of paths or dict mapping)

### Execution Parameters

* **`cwd`**: Working directory inside container
* **`disposable`**: Whether to persist changes (default: True for runs, False for sessions)
* **`preserve_env`**: Whether to persist `env` values into the resulting image environment
* **`tag`**: Tag to assign to the resulting image after execution (e.g. `tag="myapp:v2"`)

## Result Objects

Command execution returns result objects with:

* **`stdout`**: Command output as string (or specified type)
* **`stderr`**: Error output as string (or specified type)
* **`exit_code`**: Process exit code (0 = success)
* **`uuid`**: UUID of the resulting image state


# Sandboxes for SWE agents
Source: https://docs.tokenfactory.nebius.com/sandboxes/swe-agents



Researching SWE agents is hard: there are thousands of heavy-weight environments, setup is slow, and reproducibility is fragile. Sandboxes provides a branchable, VM-isolated sandbox designed for rapid experimentation across thousands of SWE environments — over 7,000 are preloaded out of the box.

## Purpose-built for SWE agent research

* Thousands of ready-to-run SWE environments, so you can benchmark agents with minimal infrastructure setup.
* Git-like branching to try multiple patches or strategies in parallel from the same checkpoint, then keep only the winning branch: MCTS, beam search, rollbacks, value-function estimation.
* VM-level isolation with per-run metrics to keep generated code contained and experiments auditable.

## Environment catalog

Pick from the preloaded catalog rather than building or pulling terabytes of images yourself. What's included now:

* [SWE-bench Verified](https://huggingface.co/datasets/princeton-nlp/SWE-bench_Verified)
* [SWE-rebench](https://huggingface.co/datasets/nebius/SWE-rebench/viewer/default/filtered)
* [SWE-rebench-V2](https://huggingface.co/datasets/nebius/SWE-rebench-V2)

## Integrations

<Columns>
  <Card title="Contree CLI" icon="terminal" href="/sandboxes/cli">
    Terminal-first agent workflows, scripted runs, session branching, and filesystem inspection.
  </Card>

  <Card title="Contree SDK" icon="python" href="/sandboxes/sdk">
    Integrate your own agent via contree-sdk.
  </Card>

  <Card title="Contree MCP" icon="plug" href="/sandboxes/mcp">
    Plug sandboxes into AI assistants that speak the Model Context Protocol.
  </Card>
</Columns>


# Switch to Token Factory
Source: https://docs.tokenfactory.nebius.com/switch



Nebius Token Factory provides an OpenAI-compatible API, making it easy to migrate existing OpenAI integrations with minimal changes.

## Switching from OpenAI

Here is a standard OpenAI example:

```python theme={null}
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5.2",
    input="Write a one-sentence bedtime story about a unicorn."
)
print(response.output_text)
```

To switch to Nebius Token Factory:

1. **Set the `base_url`** to the Token Factory endpoint:<br />`https://api.tokenfactory.nebius.com/v1/`
2. **Set your API key** using the `NEBIUS_API_KEY` environment variable. Get your key at: [https://tokenfactory.nebius.com/](https://tokenfactory.nebius.com/)
3. **Specify the model** you want to use (for example, `moonshotai/Kimi-K2.5`).

That's it - no other changes are required.

## Full Example Using Token Factory

```python lines theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenfactory.nebius.com/v1/",
    api_key=os.environ.get("NEBIUS_API_KEY")
)

response = client.chat.completions.create(
    model="moonshotai/Kimi-K2.5",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Write a haiku about cats"
                }
            ]
        }
    ]
)

print(response.to_json())
```


# Groups & Access management
Source: https://docs.tokenfactory.nebius.com/team-access/groups

Learn about access management on different levels

Being listed as a user in an organization does **not** automatically grant access to its resources.\
Each user or service account must be assigned to a **group** that defines their access level within the organization or its projects.

Groups exist at two levels:

* **Organization-level Groups** — control access to organization-wide settings and projects.
* **Project-level Groups** — control access to resources within individual projects.

### **Organization-level Groups**

Organization-level groups define permissions for managing the overall workspace, its billing, and projects.

| **Group**           | **Description**                                                                                                                                        |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**           | Full access to organization settings, billing, and all projects. Can invite external users, manage organization projects, and configure access rights. |
| **Billing Manager** | Can manage billing settings and view usage statistics across the organization. Cannot access project resources or invite users.                        |
| **No Group**        | Users added without a role at the organization level. They can later be granted access to specific project-level resources.                            |

#### **Organization-level Permissions**

| **Action**                       | **Admin**                    | **Billing Manager**          |
| :------------------------------- | :--------------------------- | :--------------------------- |
| **Usage & Consumption**          | View                         | View                         |
| **Projects and Resources**       | View, Create, Update, Delete | No Access                    |
| **Billing Settings**             | View, Create, Update, Delete | View, Create, Update, Delete |
| **Payments**                     | View                         | View                         |
| **Organization Access (Users)**  | View, Add, Remove            | No Access                    |
| **Zero Data Retention Settings** | View, Change                 | No Access                    |

<Note>
  **Note:** Organization Admins automatically have administrative privileges across all projects in the organization.
</Note>

### **Project-level Groups**

Project-level groups control access to specific project resources and operations.

| **Group**  | **Description**                                                                                              |
| :--------- | :----------------------------------------------------------------------------------------------------------- |
| **Admin**  | Full control over project resources. Can invite organization members to the project and manage their access. |
| **Member** | Can create and manage project resources but cannot invite new users or change access permissions.            |

#### **Project-level Permissions**

| **Action**                  | **Admin**         | **Member**                  |
| :-------------------------- | :---------------- | :-------------------------- |
| **Project Access (Users)**  | View, Add, Remove | No Access                   |
| **API Keys**                | Create, Delete    | Create, Delete own API keys |
| **Files API**               | Full Access       | Full Access                 |
| **Fine-tuning API**         | Full Access       | Full Access                 |
| **Batch API**               | Full Access       | Full Access                 |
| **Dedicated Endpoints API** | Full Access       | Full Access                 |
| **Prompt Presets**          | Full Access       | Full Access                 |
| **Public Endpoints API**    | Full Access       | Full Access                 |

### **Inviting Users to Groups**

To grant access to organization or project resources:

1. Invite a user to the organization.
2. Assign the user to the appropriate **Organization Group** or **Project Group**.

For detailed instructions, see the [**User Invitations**](https://docs.tokenfactory.nebius.com/team-access/invitations) section.


# User Invitations
Source: https://docs.tokenfactory.nebius.com/team-access/invitations

Learn how to invite new users to Organization and add users to Projects

## **Inviting Users to an Organization**

Users with **Organization Admin** rights can invite new users to join the organization.\
Invitations are sent by email and remain valid for **three days**. Once accepted, the user can sign in using any available authentication method.

### **To invite a user through the Web UI**

1. In the top header, open the **Organization** dropdown and click the **cog**  <Icon icon="cog" />  **icon**.
   * Alternatively, click your **Profile** icon and select **Organization Settings** from the menu.
2. On the **Organization** page, open the **Team & Access** tab.
3. Click **Invite**.
4. In the dialog window, enter the **email address** of the user you want to invite.
5. (Optional) Select an **Organization Group** to assign the appropriate access level.
   * You can change the user’s group at any time.
   * For more details, see [**Organization Groups**](https://docs.tokenfactory.nebius.com/team-access/groups#organization-level-groups).
6. Click **Invite**.

An invitation email will be sent to the specified address.\
Once the user accepts, they can sign in and access the organization based on their assigned group.

## **Inviting Users to a Project**

Users with **Project Admin** rights can add existing members of the organization to a specific project.\
If you also have **Organization Admin** rights, you can invite new users directly to both the organization and the project.

### **To invite a user through the Web UI**

1. In the top header, open the **Project** dropdown and click the **cog**  <Icon icon="cog" />  **icon**.
   * Alternatively, click your **Profile** icon and select **Project Settings** from the menu.
2. On the **Project** page, open the **Team & Access** tab.
3. Click **Invite**.
4. In the dialog window, choose one of the following options:
   * **Invite new users** (requires Organization Admin rights): specify the user’s email to invite them to both the organization and the project.
   * **Add existing users**: select users who are already part of the organization and grant them project access.
5. (Optional) Assign the user to a **Project Group** to define their permissions.
   * You can change the group assignment at any time.
   * For more details, see [**Project Groups**](https://docs.tokenfactory.nebius.com/team-access/groups#project-level-groups).
6. Click **Invite**.

The user will immediately gain access to the project once added or once their invitation is accepted.


# Organizations and Projects
Source: https://docs.tokenfactory.nebius.com/team-access/org-projects

Learn how to work with Organizations and Projects in Nebius Token Factory

### **Hierarchy Overview**

The **Nebius Token Factory resource model** follows a simple hierarchical structure:

**Organization → Projects → Resources**

* At the top level, the **Organization** defines your overall workspace and user management.
* Each **Project** within an organization acts as an isolated environment for related resources and teams.
* **Resources**—such as models, endpoints, files, and datasets—exist inside a project and inherit its access settings.

```mermaid theme={null}
%%{init: {"flowchart": {"nodeSpacing": 25, "rankSpacing": 40}}}%%
flowchart LR
  classDef rounded stroke:#4C37DC,fill:#1E1E1E,color:#fff,rx:15,ry:15;

  Org["Organization"]
  Org --> A["Project A"]
  Org --> B["Project B"]

  A --> A1["API Keys"]
  A --> A2["Fine-tuning Jobs"]
  A --> A3["Dedicated Endpoints"]
  A --> A4["Files & Datasets"]

  B --> B1["API Keys"]
  B --> B2["Fine-tuning Jobs"]
  B --> B3["Datasets"]

  class Org,A,B,A1,A2,A3,A4,B1,B2,B3 rounded;
```

***

### **Organization**

An **organization** represents your primary workspace in Nebius Token Factory. It serves as a container for all your projects, access settings, and user accounts.

An organization includes:

* **Projects** that contain your compute, storage, and AI resources
* **Organization Groups** that define identity and access configurations
* **User accounts** with assigned groups and permissions

When you sign up for Nebius Token Factory, a personal organization is created automatically.\
You can also:

* Be invited to other organizations and collaborate on their projects
* Create additional organizations for separate teams or business units

To grant a user access to organizational resources, add them to the relevant **Organization Group**.

***

### **Projects**

A **project** is a logical container for your Nebius Token Factory resources. Projects help you organize assets and manage permissions within an organization.

Within a project, you can create and manage:

* **API keys**
* **Fine-tuning jobs**
* **Dedicated endpoints**
* **Files and datasets**

Each project includes **Project Groups** that control access to project resources.\
Projects can be **multi-region**, allowing you to group resources by product, team, use case, or any other organizational criteria.

When you first sign up for Nebius Token Factory, a **default project** is created automatically for your resources.


# Overview
Source: https://docs.tokenfactory.nebius.com/team-access/overview

Collaborate securely with Team Management & Role-Based Access

**Teams & Access Management** enables centralized control over user access to your resources. It ensures that only authorized users and accounts with assigned permissions can interact with your organization’s assets.

**Key Capabilities**

<Columns>
  <Card title="Organization Management" icon="buildings" href="/team-access/groups#organization-level-groups">
    * Manage billing details and usage across your organisation
  </Card>

  <Card title="Team Invitations" icon="people-group" href="/team-access/invitations">
    * Add team members to your organization or projects
  </Card>

  <Card title="Group Assignment" icon="user-group" href="/team-access/groups">
    * Define access levels using predefined access groups
  </Card>

  <Card title="Scoped Projects" icon="diagram-project" href="/team-access/org-projects">
    * Split your workspace into distinct projects and invite only relevant collaborators
  </Card>

  <Card title="Granular Access Control" icon="user-key" href="/team-access/groups">
    * Manage permissions independently for each project and the overall organization
  </Card>
</Columns>

This functionality ensures **secure, compliant, and organized collaboration** across all workspaces and is available to all users, regardless of service tier.


# Configure Single Sign-On
Source: https://docs.tokenfactory.nebius.com/team-access/sso

Learn how to configure single sign-on

A federation could be configured for the Nebius Token Factory to allow your organization's users login using a SAML 2.0 compatible single sign-on provider.

SSO is configured in two systems:

* Nebius Token Factory, where you create and configure a federation.
* Identity Provider: create an application and connect the application to the federation.

After the federation and application are set up, users can sign in to Nebius Token Factory.

Following 4 steps will guide you through the process.

## 1. Create an application in the Identity Provider

<Tabs>
  <Tab title="Okta">
    Go to Admin Console → Applications → Application and choose "Create App Integration".

    Choose "SAML 2.0" sign-in method and set the following parameters on the next screen:

    * **Single sign-on URL**: [https://auth.tokenfactory.nebius.com/login/saml2/provider/federation-id](https://auth.tokenfactory.nebius.com/login/saml2/provider/federation-id)
    * **Audience URI (SP Entity ID)**: [https://auth.tokenfactory.nebius.com/saml2/rp/federation-id](https://auth.tokenfactory.nebius.com/saml2/rp/federation-id)
    * **Name ID format**: Unspecified
    * **Application username**: Okta username

    Continue and tick the option "This is an internal app that we have created" on the next screen.

    <Note>
      **Note**

      `federation-id` is used temporarily until you create a federation and get its ID. After that, replace `federation-id` with an actual one.
    </Note>
  </Tab>
</Tabs>

## 2. Create a federation in Nebius Token Factory

<Tabs>
  <Tab title="CLI">
    1. Install the Nebius CLI tool (an installation script works for macOS and Linux):

       ```
       curl -sSL https://storage.eu-north1.nebius.cloud/cli/install.sh | bash
       ```
    2. Create a configuration profile:

       ```
       nebius profile create \
         --profile <profile name of your choice> \
         --endpoint api.nebius.cloud \
         --federation-endpoint auth.tokenfactory.nebius.com \
         --parent-id <organization ID>
       ```

       An organization ID starts with `aitenant-` and could be found on [the organization settings page](https://tokenfactory.nebius.com/organization/projects).
    3. Run the following command:

       ```
       nebius iam federation create \
          --parent-id <organization ID> \
          --name <federation name> \
          --user-account-auto-creation=true \
          --active=true \
          --saml-settings-sso-url <login URL> \
          --saml-settings-idp-issuer <Identity Provider Issuer URI>

       ```
    4. Copy and save the federation ID. It is returned in the `metadata.id` field of the command output.
  </Tab>
</Tabs>

## 3. Change the SAML settings of the application

<Tabs>
  <Tab title="Okta">
    1. Replace `federation-id` with an actual federation ID in the Okta application configuration.
    2. Navigate to the application configuration page on the Admin Console.
    3. Then scroll down to the "SAML Settings" section and replace `federation-id` with the created federation ID in the following fields:
       * Single Sign On URL: `https://auth.tokenfactory.nebius.com/login/saml2/provider/<your-federation-id>`
       * Recipient URL: `https://auth.tokenfactory.nebius.com/login/saml2/provider/<your-federation-id>`
       * Destination URL: `https://auth.tokenfactory.nebius.com/login/saml2/provider/<your-federation-id>`
       * Audience Restriction: `https://auth.tokenfactory.nebius.com/saml2/rp/<your-federation-id>`
  </Tab>
</Tabs>

## 4. Add a signing certificate to the federation

Download a certificate from the Identity Provider.

<Tabs>
  <Tab title="Okta">
    1. Navigate to the application configuration page on the Admin Console.
    2. Switch to the "Sign On" tab and scroll down to the "SAML Signing Certificates" section.
    3. Push "Generate new certificate" and then "Actions → Download certificate" on a line with freshly created active certificate.
  </Tab>
</Tabs>

Then, add the certificate to the federation:

<Tabs>
  <Tab title="CLI">
    1. Prepare the `certificate.json` file:

       ```
       {
         "metadata": {
           "parent_id": "<federation_ID>"
         },
         "spec": {
           "description": "certificate for a federation",
           "data": "-----BEGIN CERTIFICATE-----\n<certificate_body>\n-----END CERTIFICATE-----\n"
         }
       }
       ```

       Specify the certificate body from the downloaded file and the federation ID.

       In this file, the certificate body is split into several lines. Paste it as a single line to `federation-cert.json`.
    2. Apply the certificate file:

       ```
       nebius iam federation-certificate create --file federation-cert.json
       ```
  </Tab>
</Tabs>

## Log in to Nebius Token Factory using the configured SSO

1. Open the Nebius Token Factory web console.
2. Click the Get started with SSO button.
3. Enter the federation ID and click the Sign in button.

A successful login means that you have correctly configured the federation and SSO.

## Assigning new users to the groups

SSO users are not included in any Access groups on first login. An organization administrator should assign them to an Access group to provide the required permissions on the platform.


# Prompt presets
Source: https://docs.tokenfactory.nebius.com/utilities/prompt-presets

Learn how to save your prompts and reuse them

[**Prompt presets**](https://tokenfactory.nebius.com/prompt-presets) let you save and reuse model setups you’ve tested in Nebius Token Factory, making it easy to manage and share configurations.

In the **Inference playground**, you can store the model parameters, system prompt, and few-shot examples as a prompt preset. Saved presets appear on the [**Prompt presets**](https://tokenfactory.nebius.com/prompt-presets) page, where you can:

* Reopen them in the playground for further testing
* Export them as code for integration into your application
* Share them with your team

### Prompt preset contents

A prompt preset is based on a single model setup from the playground and includes:

* **Text-to-text model** — Other model types are not supported.
* **Model parameters** available in the playground (e.g., temperature, max tokens). Parameters available only via API are not included.
* **System prompt** (if added in your setup).
* **Few-shot examples** — user prompts and AI responses you’ve added.

<Warning>
  Your actual chat history with the model is not saved in the preset.
</Warning>

### Creating a preset

1. In the left panel, click **Save preset**.

   If using Compare mode, click <Icon icon="circle-ellipsis-vertical" /> → **Save preset** in the panel of the desired model.
2. In the dialog, enter a name and (optional) tags.
3. Click **Save preset**.

### Using presets

You can manage all saved presets on the [**Prompt presets**](https://tokenfactory.nebius.com/prompt-presets) page.

1. **Open in playground** — Click a preset to load it back into the playground.
2. **View as code** — Click <Icon icon="circle-ellipsis-vertical" /> → **View code** to generate code for use in your app.
3. **Share** — Click <Icon icon="circle-ellipsis-vertical" /> → **Share** to copy a URL.

<Note>
  Recipients must have a Nebius Token Factory account to access presets and other inference features.
</Note>