cortex-training 0.1.0

Cortex Training, Snowflake's serverless offering for customizing and deploying open-weight LLMs. With Cortex Training, teams can use familiar training frameworks, or build advanced custom training loops with low-level serverless APIs - all without managing the complexities of GPU provisioning, scheduling, checkpointing and distributed execution.

Cortex Training is built on top of the highly customizable and optimized open-source Arctic Platform backend to bring the flexibility and efficiency of complex, self-managed bare-metal training cluster to a simplified serverless experience. AI teams no longer have to trade simplicity for flexibility or cost efficiency when customizing and deploying models. See our blog for details.

This repository contains the Python SDK, CLI, model catalog, and recipes for using Cortex Training.

What's in this repository

Getting Started

Setup

1. Clone and install — this gives you the SDK, CLI, and all recipes:

   git clone https://github.com/snowflakedb/cortex-training.git
   cd cortex-training
   uv venv
   source .venv/bin/activate
   uv pip install -e .
   

   Alternatively, uv pip install cortex-training installs the SDK and CLI without the recipes.

2. Get access — you need a Snowflake account with Cortex Training enabled. See account setup for the full walkthrough and authentication for PAT generation and connection configuration.

3. Connect — Cortex Training signs in with a standard Snowflake connection profile, the same kind the Snowflake CLI and Python Connector use. The easiest way to set one up is to run:

   cortex-training login
   

   It creates or picks a profile, checks that it connects to Cortex Training, and saves it as the one to use. Every command, the TUI, and the recipes then use it with no extra arguments:

   cortex-training capacity
   

   To write the profile yourself instead, add it to connections.toml in your Snowflake folder, usually ~/.snowflake/connections.toml. cortex-training login prints the exact file it uses; if it printed another path, use that one:

   [cortex-training]
   account = "ACCOUNT"
   host = "ACCOUNT.snowflakecomputing.com"
   user = "USER"
   role = "ROLE"
   authenticator = "PROGRAMMATIC_ACCESS_TOKEN"
   token = "YOUR_PROGRAMMATIC_ACCESS_TOKEN"
   database = "CORTEX_TRAINING_DB"
   schema = "PUBLIC"
   

   Then protect the file (use the path login printed, if different) and check the profile:

   chmod 600 ~/.snowflake/connections.toml
   cortex-training login cortex-training
   

   Pass --connection NAME (or connection=NAME to a recipe) to use another profile for one command. See authentication for other sign-in methods, such as key pairs.

Already using a JSON connection file?

If you connect with a JSON file (host, pat, database, schema), for example through --config, CORTEX_TRAINING_CONFIG, cortex-training login FILE, or a recipe's config=, convert it into a profile with one command:

cortex-training login --convert-legacy-config ~/cortex-training-config.json

It shows what it will change and asks first: it checks the token, adds a profile, saves it as the one to use, and signs in with it. Your JSON file is kept as it was, so you can go back to it with --config FILE. JSON files still work, and will be deprecated in a future release.

Hello World with Cortex Training

Fine-tune a chat model on a small bundled dataset:

uv pip install 'tinker-cookbook @ git+https://github.com/thinking-machines-lab/tinker-cookbook.git@nightly'
python -m recipes.sft_quickstart.conversational.train max_steps=50

It connects with the profile from step 3 and fine-tunes Qwen3-8B (full-parameter, four H200 GPUs) on a small bundled dataset. See the SFT recipes for other datasets, models, and training options.

Choose a recipe type

The complete recipe index lists the individual workflows and their entry points.

How recipes work

Recipes are runnable, end-to-end workflows that you can use as written or adapt. They build jobs from the model catalog, which contains configurations organized by model, context length, GPU type, and training mode. Select those options on the command line instead of writing a complete job body.

Each recipe README covers its prerequisites, commands, options, and expected results. See model compatibility for the currently supported combinations.

Build custom workflows

Recipes can be built on either client. With CortexTrainingClient, the recipe creates the Cortex Training job and passes its job_id to each operation. With ArcticRLClient, the recipe describes the model and its training, sampling, and optional log-probability workers; the client presents those workers through one RL API. Its backend can be Cortex Training or an on-prem Arctic Platform deployment, so it is also the better fit for portable RL recipes and framework integrations.

Documentation

• New users: account setup and first job
• Recipe users: complete recipe index
• Model selection: model compatibility and model catalog
• Core concepts: jobs, lifecycle, checkpoints, hardware, and sizing
• Operations: job management, logs and metrics, and troubleshooting
• API development: CLI, Python SDK, and REST API

Development

• Contributing to the client or recipes — see the contributing guides and recipe template. Install development dependencies with uv pip install -e ".[dev]" and run python3 -m pytest tests/ -q.
• Building a distributable package — use ./build_wheel.sh.