> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Hub Privacy & Upload Options
> Every praisonai-train Hub push is private by default — opt in to publish, tune the commit, tags, and save method
Every Hub push from `praisonai-train` is private by default. Set `hf_private: false` in `config.yaml` to publish.
Prior to PraisonAI [PR #4357](https://github.com/MervinPraison/PraisonAI/pull/4357), every training run that set `huggingface_save: true` uploaded to a **public** repo, silently — LLM, vision, and standalone upload paths alike. From this release the default is **private**. If you were relying on the old behaviour, add `hf_private: false` to your config.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Hub push"
C[⚙️ config.yaml] --> K[🔑 HF_TOKEN]
K --> P{🔒 hf_private?}
P -->|default true| Priv[🗝️ Private repo]
P -->|false| Pub[🌐 Public repo]
end
classDef in fill:#8B0000,stroke:#7C90A0,color:#fff
classDef proc fill:#189AB4,stroke:#7C90A0,color:#fff
classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef out fill:#10B981,stroke:#7C90A0,color:#fff
class C in
class K proc
class P q
class Priv,Pub out
```
## Quick Start
Publish to a public repo — opt out of the private default with one key.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# config.yaml
model_name: unsloth/gemma-2-2b-it-bnb-4bit
hf_model_name: me/my-model # namespaced, always
huggingface_save: true # push after training
hf_private: false # opt-in to publish publicly
commit_message: "v0.1 from praisonai-train"
tags: ["praisonai", "gemma-2"]
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train
```
Omit `hf_private` entirely and the repo is created **private** — the safe default.
## Config keys
Every key that shapes a Hub push, read from `_hub.py::hub_push_kwargs` and the trainer's `KNOWN_KEYS`.
| Key | Type | Default | Description |
| ---------------- | ------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `hf_private` | bool | `true` | Push as a private repo. Accepts the YAML string `"false"` / `"0"` / `"no"` as opt-out. |
| `save_method` | string | `"merged_16bit"` | Passed to Unsloth's `push_to_hub_merged`. Previously hardcoded to `merged_16bit` at every push site. |
| `commit_message` | string | — | Optional commit message on the Hub. Only sent when set. |
| `tags` | list\[string] | — | Optional tags on the Hub repo. Only sent when set. |
| `hf_model_name` | string | required | Hub repo id (e.g. `me/my-model`) — see the safety note below. |
`commit_message` and `tags` are only forwarded to the Hub when you set them — leave them out and nothing extra is sent.
## Authentication
A write-scoped token, from an env var **or** a cached login — either works.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export HF_TOKEN=hf_...
# or
huggingface-cli login
```
The token must have **write** scope, and the repo must be under your own username or an org you can write to.
## Error translation
A rejected push turns into a one-line fix, not a stack trace — now shared by all three push sites (LLM, vision, and `upload-vision`) via `_hub.py::raise_hf_push_error`.
| Status | Message keyword | What to do |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------- |
| 401 | "rejected the credentials" | Run `huggingface-cli login`, or `export HF_TOKEN=…` with write scope |
| 403 | "refused write access" | Repo must be under your username / an org you can write to; token needs write scope |
| other | "upload to '\' failed" | Raw upstream error preserved after the actionable prefix |
## Safety note on `hf_model_name`
Always use the namespaced form `me/model`, never a bare name.
`praisonai-train` deletes a **local** stale output directory of that name before an upload (`_hub.py::clean_local_repo_dir`), but a namespaced repo id like `me/model` is **never** treated as a path to delete — even if `./me/model` exists locally. A bare name with no `/` **is** treated as a local directory and removed.
Setting `hf_model_name` to a bare directory name (no `/`) makes `praisonai-train` treat it as a **local** path and delete it before an export. Always prefer the namespaced form (`me/model`) so no local directory of that name can be wiped. This was a real defect in `upload_vision.py` before PR #4357.
## Best Practices
The default is private. Only add `hf_private: false` when you deliberately want a public repo — and double-check the dataset was public too.
Use `me/model`, never a bare `model`. A namespaced id is a Hub target and is never deleted as a local path.
Run `huggingface-cli login` (cached tokens count) or `export HF_TOKEN=hf_...` with write scope before the run — [preflight](/docs/features/praisonai-train#preflight-validation) fails fast if it's missing.
`commit_message` and `tags` are only sent when set — use them to label each upload on the Hub.
## Related
Publish an already-trained model to HF, GGUF, or Ollama without re-training.
Full fine-tuning flow and config.yaml reference.
Fine-tune with DPO, ORPO, or KTO preference pairs.