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

# Installation

> Set up ATLAS environment with validated dependencies

<Note>
  **SDK Only**: 30 seconds • **Full Training Stack**: 10-15 minutes
</Note>

## Choose Your Path

**Most users only need the SDK:**

```bash theme={null}
python -m pip install --upgrade arc-atlas
```

This gives you adaptive dual-agent orchestration, telemetry streaming, and data export. Skip to the [Verification](#verification) section after installation.

<Warning>
  **Only install the full training stack if you need to:**

  * Train custom teacher models with GRPO
  * Run offline reinforcement learning
  * Fine-tune models on your own hardware

  The training stack requires CUDA-capable GPUs, PyTorch 2.6.0, and vLLM 0.8.3. Most teams use pre-trained teacher models and never need this setup.
</Warning>

## System Requirements

<CardGroup cols="2">
  <Card title="Minimum Requirements" icon="desktop">
    * 2× NVIDIA GPUs with CUDA support (for RL training)
    * 1× GPU minimum for inference only
    * 32GB+ system RAM
    * 100GB+ disk space
    * Python 3.10 or newer
  </Card>

  <Card title="Recommended Setup" icon="server">
    * 4×H100 or 8×H100 GPUs (40GB+ VRAM each)
    * 128GB+ system RAM
    * 200GB+ NVMe storage
    * Ubuntu 22.04 LTS
  </Card>
</CardGroup>

## Prerequisites

<Warning>
  **Before installing:** Run this 30-second check to verify your system meets requirements.
</Warning>

```bash theme={null}
python - <<'EOF'
import sys
import subprocess

checks = []

# Check Python version
py_version = sys.version_info
checks.append(("Python 3.11 or 3.12", py_version >= (3, 11), f"Found {py_version.major}.{py_version.minor}"))

# Check CUDA
try:
    result = subprocess.run(['nvidia-smi'], capture_output=True, text=True)
    cuda_available = result.returncode == 0
    checks.append(("NVIDIA GPU", cuda_available, "Found" if cuda_available else "Not found"))
except:
    checks.append(("NVIDIA GPU", False, "nvidia-smi not available"))

# Check disk space
import shutil
stat = shutil.disk_usage("/")
free_gb = stat.free / (1024**3)
checks.append(("200GB+ free disk", free_gb >= 200, f"{free_gb:.1f}GB free"))

# Print results
print("\nPrerequisites Check:")
print("-" * 50)
for name, passed, detail in checks:
    status = "✅" if passed else "❌"
    print(f"{status} {name}: {detail}")

all_passed = all(c[1] for c in checks)
print("-" * 50)
if all_passed:
    print("✅ All checks passed! Proceed with installation.")
else:
    print("❌ Some checks failed. Review requirements before installing.")
    sys.exit(1)
EOF
```

**Expected output:**

```
Prerequisites Check:
--------------------------------------------------
✅ Python 3.11 or 3.12: Found 3.11
✅ NVIDIA GPU: Found
✅ 200GB+ free disk: 245.3GB free
--------------------------------------------------
✅ All checks passed! Proceed with installation.
```

<Note>
  **SDK-only users can skip this.** This check is only needed for the full training stack (Atlas Core).
</Note>

<Steps>
  <Step title="Set up CUDA">
    Ensure NVIDIA drivers and CUDA are installed and compatible with PyTorch 2.6.0:

    ```bash theme={null}
    nvidia-smi  # Verify CUDA version
    ```
  </Step>

  <Step title="Python Environment">
    Verify Python version (3.10 or newer required):

    ```bash theme={null}
    python --version
    ```
  </Step>

  <Step title="Authenticate with HuggingFace">
    Authenticate for model and dataset access:

    ```bash theme={null}
    huggingface-cli login
    ```
  </Step>
</Steps>

## Installation Methods

<Tabs>
  <Tab title="Runtime SDK (Minimal)">
    ```bash theme={null}
    python -m pip install --upgrade arc-atlas
    ```

    <Tip>
      Keep credentials such as `ANTHROPIC_API_KEY` in a `.env` file and load them before orchestrating runs. Atlas defaults to Anthropic as the primary provider.
    </Tip>

    After the package installs, bootstrap your project with autodiscovery:

    ```bash theme={null}
    atlas env init --task "Summarize the latest AI news"
    atlas run --config .atlas/generated_config.yaml --task "Summarize the latest AI news"
    ```

    The CLI writes `.atlas/discover.json`, optional factory scaffolds, and metadata snapshots while automatically loading `.env` and extending `PYTHONPATH`. `atlas env init` now handles storage setup automatically—no need to run `atlas init` separately. Re-run `atlas env init --scaffold-config-full` whenever you want a fresh runtime configuration derived from discovery output.
  </Tab>

  <Tab title="Automated Training Setup (Recommended)">
    Use our validated installation scripts for the smoothest setup:

    **For Python 3.11:**

    ```bash theme={null}
    bash scripts/install_py311.sh
    ```

    **For Python 3.12:**

    ```bash theme={null}
    bash scripts/install_py312.sh
    ```

    These scripts automatically:

    * Install PyTorch with CUDA 12.4 support
    * Configure vLLM 0.8.3
    * Set up Flash Attention
    * Install all dependencies
  </Tab>

  <Tab title="Docker (Reproducible)">
    Build a pinned training image directly from this repo:

    ```bash theme={null}
    docker build -t atlas-core:local .
    ```

    Run the offline pipeline helper against a JSONL export:

    ```bash theme={null}
    docker run --rm \
      -v "$(pwd)/exports:/data" \
      atlas-core:local \
      atlas-core offline-pipeline --export-path /data/traces.jsonl --dry-run
    ```

    For GPU hosts, rebuild with CUDA-enabled base images and include extras such as
    `deepspeed`, `ray`, or `vllm`.
  </Tab>

  <Tab title="Manual Training Installation">
    For custom environments or debugging:

    ```bash theme={null}
    # Install PyTorch with CUDA support
    python -m pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu124

    # Install vLLM and TensorBoard
    python -m pip install vllm==0.8.3 tensorboard

    # Install Flash Attention (for optimal performance)
    python -m pip install flash-attn --no-build-isolation

    # Install FlashInfer
    python -m pip install flashinfer-python -i https://flashinfer.ai/whl/cu124/torch2.6/

    # Install remaining dependencies
    python -m pip install --upgrade -r requirements-py311.txt  # or requirements-py312.txt
    ```
  </Tab>

  <Tab title="Conda Environment">
    Create isolated environment with Conda:

    ```bash theme={null}
    # Create environment
    conda create -n atlas python=3.11
    conda activate atlas

    # Install PyTorch
    conda install pytorch==2.6.0 pytorch-cuda=12.4 -c pytorch -c nvidia

    # Run installation script
    bash scripts/install_py311.sh
    ```
  </Tab>
</Tabs>

## Configure Environment

### API Keys

```bash theme={null}
# Training stack
export HF_TOKEN="your-huggingface-token"
export WANDB_API_KEY="your-wandb-key"  # Optional

# Runtime SDK
export ANTHROPIC_API_KEY="sk-ant-your-key"  # Primary provider
export GEMINI_API_KEY="your-gemini-key"  # Optional for rewards
```

<Tip>
  Store secrets in `.env`. The Atlas CLI loads `.env` automatically and extends `PYTHONPATH` with your project root and `src/` directory.
</Tip>

### Disable Tracking

To disable Weights & Biases tracking:

```bash theme={null}
# In command line
atlas-core train report_to=null

# Or in config file
report_to: null
```

## Verification

After installation, verify your setup:

### 3-Minute Smoke Test

<Note>
  Run this once to confirm CUDA, vLLM, and model downloads are working before you invest in longer training jobs.
</Note>

```bash theme={null}
python - <<'PY'
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Load teacher model
teacher = AutoModelForCausalLM.from_pretrained(
    "Arc-Intelligence/ATLAS-8B-Thinking",
    device_map="auto",
    torch_dtype=torch.float16
)
teacher_tokenizer = AutoTokenizer.from_pretrained(
    "Arc-Intelligence/ATLAS-8B-Thinking"
)

print("CUDA available:", torch.cuda.is_available())
print("GPU count:", torch.cuda.device_count())
print("Teacher model loaded:", teacher.config.model_type)
print("Model device:", next(teacher.parameters()).device)
PY
```

**Expected output:**

```
CUDA available: True
GPU count: 8
Teacher model loaded: qwen2
Model device: cuda:0
```

<CodeGroup>
  ```python "Quick Test" theme={null}
  # Verify core dependencies
  import torch
  import transformers
  import datasets
  import vllm

  print(f"PyTorch: {torch.__version__}")
  print(f"CUDA available: {torch.cuda.is_available()}")
  print(f"GPU count: {torch.cuda.device_count()}")
  print(f"Transformers: {transformers.__version__}")
  print(f"vLLM: {vllm.__version__}")
  ```

  ```bash "CLI Verification" theme={null}
  # Check accelerate installation
  accelerate --version

  # Verify CUDA
  python -c "import torch; print(torch.cuda.is_available())"

  # Test model access
  huggingface-cli download Arc-Intelligence/ATLAS-8B-Thinking \
    --include "*.json" \
    --exclude "*.safetensors"
  ```
</CodeGroup>

## GPU Memory Management

For different GPU configurations:

<AccordionGroup>
  <Accordion title="Single GPU Setup" icon="microchip">
    Single GPU is supported for inference only. For RL training, use model offloading:

    ```bash theme={null}
    # Inference only with single GPU
    python examples/quickstart/evaluate.py  # Quick evaluation test

    # For training with limited VRAM (requires 2+ GPUs)
    scripts/launch.sh offload 2 src/atlas_core/configs/recipe/teacher_rcl.yaml

    # Or use Zero-1 optimization
    scripts/launch.sh zero1 2 src/atlas_core/configs/recipe/teacher_rcl.yaml
    ```
  </Accordion>

  <Accordion title="Multi-GPU Setup" icon="layer-group">
    For distributed training across multiple GPUs:

    ```bash theme={null}
    # Minimum 2 GPUs for RL training (1 for vLLM, 1 for training)
    scripts/launch_with_server.sh 1 1 src/atlas_core/configs/recipe/teacher_rcl.yaml

    # Production setup with 4 GPUs (2 for vLLM, 2 for training)
    scripts/launch_with_server.sh 2 2 src/atlas_core/configs/recipe/teacher_rcl.yaml

    # Full 8 GPU setup
    scripts/launch_with_server.sh 4 4 src/atlas_core/configs/recipe/teacher_rcl.yaml
    ```
  </Accordion>

  <Accordion title="Memory Optimization" icon="memory">
    Reduce memory usage with these settings:

    ```yaml theme={null}
    # In config file
    per_device_train_batch_size: 1
    gradient_checkpointing: true
    fp16: true  # or bf16 for A100/H100
    ```
  </Accordion>
</AccordionGroup>

## Security Best Practices

<Warning>
  Follow these security guidelines to protect sensitive information:
</Warning>

* **Never commit secrets**: Keep tokens, `.env` files, and API keys out of version control
* **Use environment variables**: Store `HF_TOKEN`, `WANDB_API_KEY`, etc. as environment variables
* **Gitignore protection**: Ensure `results/`, `logs/`, `wandb/` remain in `.gitignore`
* **Least privilege**: Restrict dataset access permissions
* **Logout on shared machines**: Run `huggingface-cli logout` after use

## Platform-Specific Notes

<Tabs>
  <Tab title="Linux">
    Tested on Ubuntu 20.04/22.04 LTS:

    * Ensure CUDA toolkit matches PyTorch requirements
    * May need `sudo` for system package installations
  </Tab>

  <Tab title="macOS">
    Limited support for Apple Silicon:

    * CPU-only mode available
    * Use MPS backend where supported
    * vLLM may not be available
  </Tab>

  <Tab title="Windows WSL2">
    Run through WSL2 for best compatibility:

    * Install CUDA toolkit in WSL2
    * Use Linux installation instructions
    * Ensure WSL2 has GPU passthrough enabled
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CUDA Version Mismatch" icon="triangle-exclamation">
    If you see CUDA errors:

    ```bash theme={null}
    # Check CUDA version
    nvidia-smi
    nvcc --version

    # Reinstall PyTorch with correct CUDA version
    pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu118  # For CUDA 11.8
    ```
  </Accordion>

  <Accordion title="Out of Memory Errors" icon="memory">
    Reduce memory usage:

    ```bash theme={null}
    # Use gradient checkpointing
    atlas-core train gradient_checkpointing=true

    # Reduce batch size
    atlas-core train per_device_train_batch_size=1

    # Enable CPU offloading
    scripts/launch.sh offload 2 src/atlas_core/configs/recipe/teacher_rcl.yaml
    ```
  </Accordion>

  <Accordion title="HuggingFace Access Denied" icon="lock">
    Ensure proper authentication:

    ```bash theme={null}
    # Re-authenticate
    huggingface-cli logout
    huggingface-cli login

    # Verify token
    huggingface-cli whoami
    ```
  </Accordion>

  <Accordion title="vLLM Installation Fails" icon="xmark">
    Common vLLM issues:

    ```bash theme={null}
    # Install build dependencies
    sudo apt-get install python3-dev

    # Try pre-built wheel
    pip install https://github.com/vllm-project/vllm/releases/download/v0.8.3/vllm-0.8.3-cp311-cp311-linux_x86_64.whl
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols="2">
  <Card title="Quickstart" icon="rocket" href="/sdk/quickstart">
    Deploy ATLAS with pre-trained models
  </Card>

  <Card title="Offline Training" icon="flask" href="/training/offline/grpo-training">
    Run your first ATLAS training experiment
  </Card>
</CardGroup>