Hugging Face Visual Guide

Know the three token types

Go to huggingface.co/settings/tokens. Choose fine-grained (scoped to specific repos/orgs — recommended for production), read (read-only on all private content), or write (read + write everywhere — use sparingly).

Create one scoped token per use

One token per app or machine, so a leak only invalidates one usage. Never paste raw tokens into commands (shell history); pass them via an environment variable. For CI/CD, prefer Trusted Publishers — OIDC identity, no stored secret.

# pass the token, never type it into history
export HF_TOKEN=hf_xxx   # then use --token $HF_TOKEN

Turn on two-factor authentication

Settings → hf.co/settings/authentication → "Add Two-Factor Authentication" with any TOTP app. You'll be prompted at login and every 30 days — download the recovery codes and store them safely.

Use private repos & org roles

Toggle repos private in their Settings tab (others get a 404; not searchable or clonable). Spaces get a third protected mode: code private, app public. In orgs, assign least-privilege roles.

Have a leak plan

Revoke compromised tokens immediately at settings/tokens. Manage multiple credentials with the CLI, and rely on the Hub's automatic malware / pickle / hard-coded-secret scanning on every repo.

hf auth ls                 # list stored credentials
hf auth switch --token-name prod   # switch active token
hf auth logout --token-name old    # remove one

Create the Space and pick an SDK

At huggingface.co/new-space choose a name, license, visibility and SDK: Gradio, Docker, static (or Streamlit via YAML). Or create from the CLI.

hf repos create my-demo --repo-type space --template gradio

Write the README front matter (required)

The build is driven by YAML at the top of README.md. Required keys:

---
title:     My Demo
emoji:     🚀
colorFrom: blue        # red|yellow|green|blue|indigo|purple|pink|gray
colorTo:   purple
sdk:       gradio      # gradio | docker | static | streamlit
sdk_version: 5.0.0     # for gradio / streamlit
app_file:  app.py      # entry point (static: dist/index.html)
license:   mit
---
# Docker only:  app_port: 7860   (default 7860)
# Optional:     suggested_hardware, python_version, models, datasets

Write the app — use Secrets, not hard-coded keys

Add requirements.txt for Python SDKs (Spaces installs it). In Space Settings, Variables are public and copied on duplication; Secrets are write-only, never readable again. Both arrive as environment variables.

import os, gradio as gr
model_id = os.getenv("MODEL_REPO_ID")   # from Variables/Secrets
gr.Interface(fn=predict, inputs="text", outputs="text").launch()

hf spaces secrets add my-demo API_KEY "sk-..."   # set a secret via CLI

Choose hardware

Default is CPU Basic (2 vCPU / 16 GB). Upgrade in Settings → Hardware, or from Python — and downgrade back when done so you don't pay for idle GPUs.

from huggingface_hub import HfApi
api = HfApi()
api.request_space_hardware("you/my-demo", hardware="t4-medium")
api.get_space_runtime("you/my-demo").stage   # RUNNING / BUILDING / ...

Push code — every commit rebuilds

A Space is a git repo: push a commit and it auto-rebuilds and restarts. Egress is limited to ports 80 / 443 / 8080. Free hardware sleeps when idle; paused Spaces aren't billed.

git clone https://huggingface.co/spaces/you/my-demo
# edit app.py, then:
git add . && git commit -m "update app" && git push

Authenticate with the hf CLI

The new CLI logs in via a browser device-code flow, or directly with a token. Verify who you are and what's stored.

hf auth login                    # interactive device-code flow
hf auth login --token $HF_TOKEN --add-to-git-credential  # for git push
hf auth whoami && hf auth ls

Create the model repo

hf repos create my-cool-model          # default repo type: model
# or from Python:
api.create_repo(repo_id="you/my-cool-model", private=True)

Save the model and push it

save_pretrained writes config.json + safetensors; the CLI uploads them. Upload auto-creates the repo if it doesn't exist.

# Python — save locally
model.save_pretrained("./my-cool-model-dir")
tokenizer.save_pretrained("./my-cool-model-dir")

# CLI — push
hf upload you/my-cool-model ./my-cool-model-dir .
hf upload you/my-cool-model model.safetensors /sub/dir/model.safetensors

Download & run with auth

Pass the token explicitly (from the environment, never hard-coded) and the model runs anywhere your token has access to.

import os
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "you/my-cool-model",
    token=os.environ["HF_TOKEN"],
)

# or just download files first:
hf download you/my-cool-model --local-dir ./dir

Serve it — Inference Providers

Run hosted inference through the InferenceClient without managing any server. The provider picks the route (auto, hf-inference, together, groq, fal-ai, …).

from huggingface_hub import InferenceClient

client = InferenceClient(provider="auto", api_key=os.environ["HF_TOKEN"])
image  = client.text_to_image("Astronaut riding a horse",
                              model="black-forest-labs/FLUX.1-schnell")

Start from the encrypted baseline

All Inference Endpoints use TLS in transit; HF stores no customer payloads or tokens; logs are kept 30 days. Hub and Inference Endpoints are SOC 2 Type 2 certified, with a GDPR DPA available via Enterprise.

Lock down the endpoint itself

Point endpoints at private model repos and configure endpoint authentication (Hub tokens or custom auth) in the endpoint's configuration page — so only callers you authorize can reach the model.

Keep traffic inside your VPC — AWS PrivateLink

In the endpoint configuration → Network, enable AWS PrivateLink and enter the AWS Account ID that owns your VPC. Traffic never crosses the public internet; you see only the ENI in your VPC.

api.create_inference_endpoint(
    "my-endpoint", model="meta-llama/Llama-3.1-8B-Instruct", ...,
    private_link_account_id="123456789012",
    private_link_region="us-east-1",
)

Match the Spaces to the policy

Private Spaces: code + app visible only to owner/collaborators — others get a 404, no embed URL. Protected: code private, app public at *.hf.space. Pick per app, never all-public by default.

Harden the Hub side

Automatic malware / pickle / secret scanning on every repo, GPG-signed commits, SSH-based git auth, org SSO, and Resource Groups for fine-grained repo access control in Team/Enterprise plans.