Configuration reference

Hangar reads its configuration from a YAML file (hangar server --config hangar.yaml, or the HANGAR_CONFIG environment variable), then from HANGAR_* environment variables, then from --set key=value flags. Later sources win. Hangar checks the whole configuration on start and reports every problem at once.

Every key is also an environment variable: storage.s3.bucket is HANGAR_STORAGE_S3_BUCKET. List values in environment variables and flags are comma-separated. oidc.providers takes a JSON array.

Sizes accept a number of bytes or a unit such as KiB, MiB, GiB or GB. Durations use Go syntax, such as 90s, 30m or 720h.

server

HTTP server and process settings.

Key	Type	Default	Description
server.public_url HANGAR_SERVER_PUBLIC_URL	string	""	The URL clients use to reach Hangar. Required. Used in redirects, LFS links and git URLs.
server.listen HANGAR_SERVER_LISTEN	string	:8080	Address to listen on for HTTP.
server.role HANGAR_SERVER_ROLE	string	all	Process role: all, web or worker. SQLite needs all.
server.data_dir HANGAR_SERVER_DATA_DIR	string	/var/lib/hangar	Directory for local state: the SQLite lock file and the generated secrets.yaml.
server.trusted_proxies HANGAR_SERVER_TRUSTED_PROXIES	list of strings	[]	CIDR ranges of reverse proxies whose X-Forwarded-For and X-Forwarded-Proto headers Hangar trusts.
server.max_request_body HANGAR_SERVER_MAX_REQUEST_BODY	size	64MiB	Body size limit for endpoints that buffer the request body. Streaming endpoints have no limit apart from quotas.
server.shutdown_timeout HANGAR_SERVER_SHUTDOWN_TIMEOUT	duration	30s	How long to let in-flight requests finish on SIGTERM. Longer downloads are cut.
server.timezone HANGAR_SERVER_TIMEZONE	string	UTC	IANA time zone for pull windows and schedules.

database

Database connection.

Key	Type	Default	Description
database.driver HANGAR_DATABASE_DRIVER	string	sqlite	sqlite or postgres.
database.dsn HANGAR_DATABASE_DSN	string	/var/lib/hangar/hangar.db	SQLite file path, or a postgres:// connection URL.
database.max_open_conns HANGAR_DATABASE_MAX_OPEN_CONNS	int	20	Maximum open database connections per process.

storage

Blob store for LFS objects, git data and uploads.

Key	Type	Default	Description
storage.backend HANGAR_STORAGE_BACKEND	string	fs	fs or s3.
storage.fs.path HANGAR_STORAGE_FS_PATH	string	/var/lib/hangar/blobs	Root directory of the Blob store.
storage.s3.endpoint HANGAR_STORAGE_S3_ENDPOINT	string	s3.amazonaws.com	S3 endpoint host, with an optional port. Use https:// or http:// to choose the scheme; the default is HTTPS.
storage.s3.region HANGAR_STORAGE_S3_REGION	string	eu-west-2	Bucket region.
storage.s3.bucket HANGAR_STORAGE_S3_BUCKET	string	hangar	Bucket name.
storage.s3.prefix HANGAR_STORAGE_S3_PREFIX	string	""	Key prefix inside the bucket.
storage.s3.access_key_id HANGAR_STORAGE_S3_ACCESS_KEY_ID	string	""	Access key ID. Leave empty to use the default credential chain, IRSA or Workload Identity.
storage.s3.secret_access_key HANGAR_STORAGE_S3_SECRET_ACCESS_KEY	string	""	Secret access key.
storage.s3.use_path_style HANGAR_STORAGE_S3_USE_PATH_STYLE	bool	false	Use path-style bucket addressing, as MinIO and some other stores need.
storage.s3.download_mode HANGAR_STORAGE_S3_DOWNLOAD_MODE	string	redirect	redirect sends clients to presigned URLs; proxy streams bytes through Hangar.
storage.s3.upload_mode HANGAR_STORAGE_S3_UPLOAD_MODE	string	direct	direct gives clients presigned URLs to upload LFS objects and parts to the store; proxy has them upload through Hangar. Use proxy when clients cannot reach the endpoint.
storage.s3.presign_ttl HANGAR_STORAGE_S3_PRESIGN_TTL	duration	1h	Lifetime of presigned download URLs.
storage.s3.retries HANGAR_STORAGE_S3_RETRIES	int	5	How many times Hangar sends a failed part or object upload again, waiting longer each time. Part bodies are spooled to the temporary directory while they are sent. 0 turns retries off.
storage.s3.startup_wait HANGAR_STORAGE_S3_STARTUP_WAIT	duration	5m	How long a server or worker keeps trying to reach the bucket at start, such as an object store whose Pod is still starting, before it exits. /readyz answers 503 while it waits. 0 exits at once.
storage.s3.stall_timeout HANGAR_STORAGE_S3_STALL_TIMEOUT	duration	2m	How long a request to the store may go without sending data or getting a response before Hangar cancels it and, for uploads, retries. Raise it on slow or congested links.

security

Secrets, sign-in and access defaults.

Key	Type	Default	Description
security.instance_key HANGAR_SECURITY_INSTANCE_KEY	string	""	32-byte key, base64-encoded, that encrypts stored secrets and signs URLs. Generated on first start if empty.
security.anonymous_read HANGAR_SECURITY_ANONYMOUS_READ	bool	false	Let anonymous users read public Repos and see user and Organisation profiles.
security.registration HANGAR_SECURITY_REGISTRATION	string	closed	Who can create an account: open, invite or closed.
security.local_login HANGAR_SECURITY_LOCAL_LOGIN	bool	true	Show the username and password form. The bootstrap admin can always sign in at /auth/login?local=1.
security.session_ttl HANGAR_SECURITY_SESSION_TTL	duration	720h	Lifetime of a UI session.
security.bootstrap_admin.username HANGAR_SECURITY_BOOTSTRAP_ADMIN_USERNAME	string	hangar-admin	Username of the bootstrap admin.
security.bootstrap_admin.password HANGAR_SECURITY_BOOTSTRAP_ADMIN_PASSWORD	string	""	Password of the bootstrap admin. Generated on first start if empty and no password_file is set.
security.bootstrap_admin.password_file HANGAR_SECURITY_BOOTSTRAP_ADMIN_PASSWORD_FILE	string	""	File that holds the bootstrap admin password.
security.bootstrap_admin.email HANGAR_SECURITY_BOOTSTRAP_ADMIN_EMAIL	string	""	Email address of the bootstrap admin.

oidc

OpenID Connect sign-in providers.

Key	Type	Default	Description
oidc.providers HANGAR_OIDC_PROVIDERS	list of objects	[]	Providers, shown as sign-in buttons. Set them in the YAML file, or as a JSON array in HANGAR_OIDC_PROVIDERS.
oidc.providers[].id	string		Stable provider ID, used in callback URLs.
oidc.providers[].name	string		Name on the sign-in button.
oidc.providers[].issuer	string		Issuer URL, used for discovery.
oidc.providers[].client_id	string		OAuth client ID.
oidc.providers[].client_secret	string	(secret)	OAuth client secret. Leave empty for public clients.
oidc.providers[].scopes	list of strings		Scopes to request.
oidc.providers[].claims	map of strings		Claim names for username, email, name and groups.
oidc.providers[].admin_groups	list of strings		Members of these groups are Instance admins. Checked at every sign-in.
oidc.providers[].org_mappings	list of objects		Groups that grant Organisation Roles. Checked at every sign-in.
oidc.providers[].org_mappings[].group	string		Group claim value.
oidc.providers[].org_mappings[].org	string		Organisation name.
oidc.providers[].org_mappings[].role	string		read, write or admin.
oidc.providers[].auto_create_users	bool		Create a User on first sign-in.

upstreams

Upstreams that Hangar can Pull from, keyed by ID. huggingface is built in.

Key	Type	Default	Description
upstreams.<id>.base_url HANGAR_UPSTREAMS_<ID>_BASE_URL	string	https://huggingface.co	Base URL of the Upstream's Hub API.
upstreams.<id>.enabled HANGAR_UPSTREAMS_<ID>_ENABLED	bool	true	Whether users can Discover and Pull from this Upstream.
upstreams.<id>.token HANGAR_UPSTREAMS_<ID>_TOKEN	string	""	Optional Instance token, used when the requesting user has not saved their own.
upstreams.<id>.namespace_prefix HANGAR_UPSTREAMS_<ID>_NAMESPACE_PREFIX	string	""	Prefix for Mirror Namespaces from this Upstream, for example hf-. Prefixed Mirrors no longer work as drop-in HF_ENDPOINT replacements.
upstreams.<id>.viewer_url HANGAR_UPSTREAMS_<ID>_VIEWER_URL	string	""	Dataset Viewer URL of the Upstream. Default: the base URL with datasets-server. added to the host.

pull

Pull scheduling and network controls.

Key	Type	Default	Description
pull.bandwidth_limit HANGAR_PULL_BANDWIDTH_LIMIT	size	0	Bytes per second across the Instance. 0 means unlimited.
pull.concurrency HANGAR_PULL_CONCURRENCY	int	4	Files transferred at once across the Instance.
pull.windows HANGAR_PULL_WINDOWS	list of strings	[]	Times when Pull transfers may run, such as 01:00-07:00, in server.timezone. Empty means any time.
pull.pull_through.enabled HANGAR_PULL_PULL_THROUGH_ENABLED	bool	false	Turn on Pull-through.
pull.pull_through.allow HANGAR_PULL_PULL_THROUGH_ALLOW	list of strings	[*]	Globs of upstream Repo IDs that may be pulled through.
pull.pull_through.min_role HANGAR_PULL_PULL_THROUGH_MIN_ROLE	string	user	Who may trigger Pull-through: anonymous or user (any signed-in user).
pull.dependencies.auto_pull_code HANGAR_PULL_DEPENDENCIES_AUTO_PULL_CODE	bool	true	Pull code Dependencies (from auto_map) automatically.
pull.dependencies.auto_pull_base_models HANGAR_PULL_DEPENDENCIES_AUTO_PULL_BASE_MODELS	bool	false	Pull the base model of adapters automatically.
pull.dependencies.max_depth HANGAR_PULL_DEPENDENCIES_MAX_DEPTH	int	5	Maximum depth of recursive Dependency Pulls.

git

git storage, push limits and the local pack cache.

Key	Type	Default	Description
git.max_blob_size HANGAR_GIT_MAX_BLOB_SIZE	size	10MiB	Largest non-LFS file accepted on push.
git.max_pack_size HANGAR_GIT_MAX_PACK_SIZE	size	2GiB	Largest pack accepted on push.
git.allow_force_push HANGAR_GIT_ALLOW_FORCE_PUSH	bool	false	Allow force-pushing default branches. Namespace admins always can.
git.compact_threshold HANGAR_GIT_COMPACT_THRESHOLD	int	20	Compact a Repo's packs when it has more live packs than this.
git.pack_grace_period HANGAR_GIT_PACK_GRACE_PERIOD	duration	1h	How long retired packs are kept before deletion. Must be longer than the longest request.
git.cache_dir HANGAR_GIT_CACHE_DIR	string	/var/cache/hangar/git	Local pack cache directory. Disposable.
git.cache_size HANGAR_GIT_CACHE_SIZE	size	10GiB	Size limit of the local pack cache.
git.timeout HANGAR_GIT_TIMEOUT	duration	1h	Wall-clock limit for one git operation.

lfs

git-lfs uploads.

Key	Type	Default	Description
lfs.multipart_threshold HANGAR_LFS_MULTIPART_THRESHOLD	size	64MiB	Objects larger than this use multipart uploads when the client supports them.
lfs.upload_url_ttl HANGAR_LFS_UPLOAD_URL_TTL	duration	24h	Lifetime of signed upload URLs.
lfs.verify_wait HANGAR_LFS_VERIFY_WAIT	duration	10m	How long a Commit waits for an LFS object that is still being verified.

hfapi

Hugging Face Hub API behaviour.

Key	Type	Default	Description
hfapi.regular_upload_max HANGAR_HFAPI_REGULAR_UPLOAD_MAX	size	10MiB	Preupload answers regular for files below this size unless .gitattributes says LFS.
hfapi.xet HANGAR_HFAPI_XET	string	ingest	ingest accepts Xet uploads; reject turns them off and asks clients to set HF_HUB_DISABLE_XET=1.
hfapi.default_namespace HANGAR_HFAPI_DEFAULT_NAMESPACE	string	""	Namespace that single-segment Repo IDs such as gpt2 redirect to. Empty turns the redirect off.

xet

Xet upload ingestion.

Key	Type	Default	Description
xet.cas_url HANGAR_XET_CAS_URL	string	""	URL of the Xet CAS endpoints. Default: /xet-cas.
xet.token_ttl HANGAR_XET_TOKEN_TTL	duration	1h	Lifetime of Xet write tokens.
xet.xorb_retention HANGAR_XET_XORB_RETENTION	duration	672h	How long xorbs are kept after their last use, so clients can deduplicate against them. Keep it longer than hf_xet's 21-day shard cache.
xet.max_file_size HANGAR_XET_MAX_FILE_SIZE	size	50GiB	Largest file a Xet upload may describe. One shard may rebuild at most four times this, counting only files not uploaded before; larger uploads get 413.

jobs

Background Job workers.

Key	Type	Default	Description
jobs.workers HANGAR_JOBS_WORKERS	int	4	Concurrent Jobs per worker process.
jobs.lease HANGAR_JOBS_LEASE	duration	1m	Lease length of a claimed Job. Renewed while the Job runs.

gc

Garbage collection of unreferenced LFS objects and git data.

Key	Type	Default	Description
gc.schedule HANGAR_GC_SCHEDULE	string	0 3 * * *	Cron schedule (5 fields) of the gc Job.
gc.grace_period HANGAR_GC_GRACE_PERIOD	duration	168h	Unreferenced LFS objects are deleted after this long.

repos

Repo lifecycle.

Key	Type	Default	Description
repos.restore_window HANGAR_REPOS_RESTORE_WINDOW	duration	168h	How long a deleted Repo can be restored before it is purged.

viewer

Dataset Viewer and Parquet export.

Key	Type	Default	Description
viewer.enabled HANGAR_VIEWER_ENABLED	bool	true	Turn on Parquet export and the Dataset Viewer.
viewer.max_convert_bytes HANGAR_VIEWER_MAX_CONVERT_BYTES	size	5GiB	Splits larger than this get a partial Parquet export.
viewer.max_scan_rows HANGAR_VIEWER_MAX_SCAN_ROWS	int	5000000	Rows scanned by one filter or search request before it returns partial results.
viewer.max_scan_seconds HANGAR_VIEWER_MAX_SCAN_SECONDS	duration	10s	Time limit of one filter or search request before it returns partial results.
viewer.max_cell_bytes HANGAR_VIEWER_MAX_CELL_BYTES	size	100KiB	Cells larger than this are truncated in Viewer responses.
viewer.max_request_bytes HANGAR_VIEWER_MAX_REQUEST_BYTES	size	300000000	Decoded Parquet data one Dataset Viewer request may hold; requests that need more answer with an error, as the Hub's do.
viewer.convert_concurrency HANGAR_VIEWER_CONVERT_CONCURRENCY	int	1	dataset.convert Jobs per worker.

telemetry

OpenTelemetry traces, metrics and logs. Standard OTEL_* variables also apply and win.

Key	Type	Default	Description
telemetry.service_name HANGAR_TELEMETRY_SERVICE_NAME	string	hangar	service.name resource attribute.
telemetry.environment HANGAR_TELEMETRY_ENVIRONMENT	string	""	deployment.environment.name resource attribute. Empty leaves it unset.
telemetry.traces HANGAR_TELEMETRY_TRACES	string	otlp	Trace exporter: otlp, console or none. otlp exports only when an OTLP endpoint is set with OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT. Ignored when OTEL_TRACES_EXPORTER is set.
telemetry.metrics HANGAR_TELEMETRY_METRICS	string	otlp	Metric exporter: otlp, prometheus, console or none. otlp exports only when an OTLP endpoint is set. Ignored when OTEL_METRICS_EXPORTER is set.
telemetry.logs HANGAR_TELEMETRY_LOGS	string	otlp	Log exporter: otlp, console or none. otlp exports only when an OTLP endpoint is set. Ignored when OTEL_LOGS_EXPORTER is set. Logs always go to stdout too.
telemetry.prometheus_listen HANGAR_TELEMETRY_PROMETHEUS_LISTEN	string	:9464	Address of the Prometheus /metrics endpoint when metrics is prometheus.
telemetry.log_format HANGAR_TELEMETRY_LOG_FORMAT	string	json	Stdout log format: json or text.
telemetry.log_level HANGAR_TELEMETRY_LOG_LEVEL	string	info	Minimum log level: debug, info, warn or error.