README.md

Cortex Training is Snowflake's serverless platform for post-training open-weight LLMs on managed GPU clusters. This repository contains the Python SDK, CLI, and ready-to-run examples, powered by the open-source Arctic Platform engine. Run reinforcement learning, supervised fine-tuning, and inference serving without managing GPU infrastructure.

Getting Started

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

   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 examples.
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 — configure a standard Snowflake connection profile, then:

   cortex-training --connection training capacity
   # With a configured default profile: cortex-training capacity

Quick Example

Run an example (recommended)

Fine-tune a chat model in one command:

uv pip install 'tinker-cookbook @ git+https://github.com/thinking-machines-lab/tinker-cookbook.git@nightly'
python -m examples.sft.conversational.train \
  config=~/cortex-training-config.json \
  max_steps=50

config= is the JSON connection file described in setup. This fine-tunes Qwen3-8B (full-parameter, four H200 GPUs) on a small bundled dataset. See the Conversational SFT example for all options.

CLI Mode

The CLI runs the same step-level operations the examples call, one at a time:

cortex-training submit examples/api/rl.json --wait               # training + sampling job
cortex-training --job JOB_ID fwd-bwd examples/api/fwd-bwd.json   # forward-backward pass
cortex-training --job JOB_ID step --lr 1e-4                      # optimizer step
cortex-training --job JOB_ID generate examples/api/generate.json # sample from the model
cortex-training cancel JOB_ID                                    # release GPUs

See the CLI reference for the full command set. To use an existing RL framework like SkyRL, see framework integrations.

Examples

Examples are end-to-end post-training and inference workflows you can run as is or customize. Each builds its job from the model catalog, which holds a tuned job file for each supported model, context and GPU type.

• Conversational SFT: supervised fine-tuning on chat datasets with LoRA or full-parameter training.
• Math GRPO: reinforcement learning for mathematical reasoning with verifiable rewards.
• Inference: serve a model or checkpoint, generate responses, and evaluate.

The example index lists every example and explains how to customize the job.

Documentation

• Getting started: set up your environment, configure credentials, and run your first job
• Concepts: jobs and sub-jobs, the training lifecycle, checkpoints, GPU hardware, and sizing
• CLI reference: all commands, flags, and usage examples
• Python SDK reference: CortexTrainingClient API for programmatic workflows
• REST API reference: HTTP endpoints and wire format
• Model compatibility: supported models, methods, and hardware configurations
• Framework integrations: run SkyRL, tinker-cookbook, or your own agent on Cortex Training

Development

• Contributing to the client or examples — see the contributing guides for documentation guidelines and the example template. Run the tests with python -m pytest tests/ -q after uv pip install -e ".[dev]".
• Building a distributable package — see build instructions.