Installation

Follow these steps to clone the Cosmos Reason1 repository from GitHub and run the Docker container.

Note

Ensure you have the necessary hardware and software prerequisites before installation.

Cosmos-Reason1 Setup

1. Clone the Cosmos-Reason1 repository from GitHub.

   git clone git@github.com:nvidia-cosmos/cosmos-reason1.git
   cd cosmos-reason1
   git submodule update --init --recursive
   

2. Set up Cosmos-Reason1 as either a Docker container or a Python environment.

   1. Docker Container: Build the Docker image from source:

      docker build -t cosmos-reason1-dev:dev .
      docker run -it --gpus all --shm-size=24G -w /workspace/cosmos_reason1 cosmos-reason1-dev:dev
      

   2. Python Environment: Set up the Python environment:

      apt-get update && apt-get install redis-server
      pip install -r requirements.txt
      pip install -e .
      

3. Generate a Hugging Face access token. Set the access token permission to ‘Read’ (the default permission is ‘Fine-grained’).

4. Add your Hugging Face token as an environment variable by adding the line to your shell config (e.g. ~/.bashrc):

   export HF_TOKEN=<your-hugging-face-token>
   

Monitoring Setup

We recommend using wandb to monitor training. Follow these steps to install and configure wandb:

1. Install wandb

   pip install wandb
   

2. Acquire your WANDB_API_KEY for login.

3. Log in to wandb:

   wandb login # Then enter your WANDB_API_KEY
   

   Alternatively, you can add the WANDB_API_KEY to your environment variables by adding it as a line to your shell config (e.g., ~/.bashrc):

   export WANDB_API_KEY=${WANDB_API_KEY}
   

When you launch training with a training script, you will see the wandb link in the logging:

wandb: Currently logged in as: ${WANDB_USER_NAME} to https://api.wandb.ai. Use `wandb login --relogin` to force relogin
wandb: Tracking run with wandb version 0.19.11
wandb: Run data is saved locally in ./outputs/qwen2-5-3b-tp2-dpn-sft/20250515101157/wandb/run-20250515_101157-20250515101157
wandb: Run `wandb offline` to turn off syncing.
wandb: Syncing run ./outputs/qwen2-5-3b-tp2-dpn-sft/20250515101157
wandb: ⭐️ View project at https://wandb.ai/${WANDB_USER_NAME}/${config.logging.project_name}
wandb: 🚀 View run at https://wandb.ai/${WANDB_USER_NAME}/${config.logging.project_name}/runs/20250515101157

Follow this link to view visual training metrics. You can also inspect the data in the local wandb folder.

Next Steps

Follow the steps in the Reason1 Training Guide to get started training the Cosmos-Reason1-7B model for your physical AI use case.