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

# local 后端

> 单机 Docker 执行器：GPU 分配、共享目录、回收

最简形态：Console 与训练容器同机，`docker run` 直起。适合单机 1\~8 卡的团队。

## 配置

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
FORGE_DEFAULT_FLEET_KIND=local
FORGE_IMAGE_NEMO_RL=registry.internal/starforge/nemo-rl:v0.7.0
FORGE_NEMO_RL_DIR=/opt/nemo-rl
FORGE_LOCAL_GPU_COUNT=8            # 0 = nvidia-smi 自动探测
FORGE_STORAGE_ROOT=/data/starforge   # 唯一存储根：缓存 / run 目录 / 状态（强烈建议）
FORGE_LOCAL_NETWORK=host           # 作业回连 console 最省事
FORGE_LOCAL_SHM_SIZE=64g           # /dev/shm；空则沿用 FORGE_K8S_SHM_SIZE 并自动转 docker 语法
FORGE_LOCAL_CPU_LIMIT=             # 可选 --cpus
FORGE_LOCAL_MEMORY_LIMIT=          # 可选 --memory
FORGE_LOCAL_CHECK_EXTERNAL_GPUS=1  # 探测平台外进程占卡（计入 blocked）
```

## 语义要点

<AccordionGroup>
  <Accordion title="GPU 原子分配" icon="lock">
    挑卡与起容器在同一把锁内完成，分配真相存在容器标签里——console 重启后从 `docker ps` 重建占用视图，不存在「幽灵占卡」。
  </Accordion>

  <Accordion title="容器回收" icon="trash-2">
    对账确认终态后，平台先归档训练侧尚未来得及上报的尾部日志，再立即删除容器。`FORGE_LOCAL_CONTAINER_TTL_S` 只兜底清理控制面故障留下的孤儿。
  </Accordion>

  <Accordion title="镜像" icon="box">
    解析顺序为单次 `--image` → 框架默认镜像 → runtime registry → catalog。tag 可用，生产复现建议 digest；用户镜像需符合 `FORGE_ALLOWED_IMAGE_REGISTRIES`。
  </Accordion>

  <Accordion title="无 NVIDIA 环境（仅测试）" icon="flask-conical">
    `FORGE_LOCAL_GPU_PASSTHROUGH=0` 仿真模式：分配 / 记账 / 标签照常，容器不带 `--gpus`。E2E 与开发机用，**生产必须保持默认直通**。
  </Accordion>
</AccordionGroup>

## Playground

支持：vLLM 容器本机起，端口自动分配，TTL 到期回收。

## 快速验证

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv run python scripts/e2e/local_loop.py     # 无 GPU 也能跑的全链路闭环
```