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

# 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 cols={2}>
  <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>