services.llmhop.sglang-quadlet.enable
Whether to enable SGLang model serving via Quadlet, optionally fronted by the SGL Model Gateway.
Type: boolean
Default:
false
Example:
true
services.llmhop.sglang-quadlet.cacheDir
Host directory bind-mounted as the Hugging Face cache for every worker.
Type: absolute path
Default:
"/var/cache/sglang"
services.llmhop.sglang-quadlet.dataDir
Home directory of services.llmhop.sglang-quadlet.user.
Used by rootless podman for container storage
(~/.local/share/containers), so it must live on a filesystem that
tolerates overlayfs.
Type: absolute path
Default:
"/var/lib/sglang"
services.llmhop.sglang-quadlet.devices
Devices exposed to every model container — passed verbatim as Quadlet
AddDevice= lines. Accepts both CDI references (recommended:
nvidia.com/gpu=…, amd.com/gpu=…, intel.com/gpu=…, …) and raw
host device paths (e.g. /dev/dri/renderD128). For CDI, the
corresponding spec must be generated on the host (e.g.
nvidia-ctk cdi generate).
Defaults to [ "nvidia.com/gpu=all" ] when
hardware.nvidia-container-toolkit.enable is set, otherwise empty
(CPU-only). Per-model devices overrides this.
Type: list of string
Default:
if config.hardware.nvidia-container-toolkit.enable then
[ "nvidia.com/gpu=all" ]
else
[ ]
Example:
[
"amd.com/gpu=all"
]
services.llmhop.sglang-quadlet.environment
Environment variables set on every model service.
Merged with services.llmhop.sglang-quadlet.models.<name>.environment; per-model
entries take precedence.
Type: attribute set of string
Default:
{ }
services.llmhop.sglang-quadlet.environmentFile
File in KEY=VALUE format forwarded to every service.
Use for secrets managed by sops-nix/agenix, e.g. a file containing
HF_TOKEN=<token> to access gated Hugging Face repositories.
Loaded before services.llmhop.sglang-quadlet.models.<name>.environmentFile, so
per-model files override these entries.
Type: null or absolute path
Default:
null
Example:
"/etc/sglang-quadlet/.env"
services.llmhop.sglang-quadlet.gateway.enable
Whether to enable the SGL Model Gateway in front of the workers. Disabled by default — llmhop already routes between every backend, and the gateway is only needed when you want SGLang’s IGW dispatch features (custom routing, prefix caching across workers, etc.) .
Type: boolean
Default:
false
Example:
true
services.llmhop.sglang-quadlet.gateway.enableMetrics
Whether to enable Prometheus metrics on the gateway.
Type: boolean
Default:
true
Example:
true
services.llmhop.sglang-quadlet.gateway.bindAddress
Host address the gateway binds its listeners to. Defaults to the loopback so external clients must go through Caddy / llmhop.
Type: string
Default:
"127.0.0.1"
services.llmhop.sglang-quadlet.gateway.digest
Immutable digest of the gateway image. Mutually exclusive with tag.
Type: null or string
Default:
null
services.llmhop.sglang-quadlet.gateway.environment
Additional environment variables set on the gateway container.
Type: attribute set of string
Default:
{ }
services.llmhop.sglang-quadlet.gateway.environmentFile
File in KEY=VALUE format forwarded to the gateway via --env-file.
Use for secrets like API keys; the gateway’s --api-key flag may also be passed via
settings if the value is non-secret.
Type: null or absolute path
Default:
null
Example:
"/etc/sglang/gateway.env"
services.llmhop.sglang-quadlet.gateway.image
Container image used for the gateway.
Type: string
Default:
"docker.io/lmsysorg/sgl-model-gateway"
services.llmhop.sglang-quadlet.gateway.metricsPort
Host port the gateway exposes Prometheus metrics on.
Ignored when enableMetrics is false.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
29000
services.llmhop.sglang-quadlet.gateway.port
Host port the gateway listens on.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
services.llmhop.sglang-quadlet.gateway.settings
Additional CLI flags forwarded to sgl-model-gateway.
true collapses to --<key>, null and empty lists are dropped, and an
attribute set is serialised to JSON.
false is dropped, since the CLI pairs --enable-X with --disable-X instead of auto-negating: write the negated key explicitly, e.g. disable-radix-cache = true;.
A list hands every element to a single flag (--<key> a b), which is what most multi-value options of this CLI take. The few that instead expect a repeated flag have to be written out one value at a time.
--worker-urls is rendered from the enabled models, so setting it here
replaces the generated list.
Type: attribute set of anything
Default:
{ }
Example:
{
api-key = "secret";
tls-cert-path = "/etc/sglang/tls/server.crt";
}
services.llmhop.sglang-quadlet.gateway.tag
Default tag of the gateway image. Mutually exclusive with digest.
Type: null or string
Default:
"latest"
services.llmhop.sglang-quadlet.gid
Host GID assigned to services.llmhop.sglang-quadlet.group.
Defaults to uid. It is also the inner-to-outer target of --gidmap.
Type: unsigned integer, meaning >=0
Default:
config.services.llmhop.sglang-quadlet.uid
services.llmhop.sglang-quadlet.group
Primary group for services.llmhop.sglang-quadlet.user.
Defaults to the user name (matching the typical 1:1 user/group layout).
Type: string
Default:
config.services.llmhop.sglang-quadlet.user
services.llmhop.sglang-quadlet.image
Container image used for every model worker.
Type: string
Default:
"docker.io/lmsysorg/sglang"
services.llmhop.sglang-quadlet.modelSettings
CLI flags forwarded to the model server for every model.
true collapses to --<key>, null and empty lists are dropped, and an
attribute set is serialised to JSON.
false is dropped, since the CLI pairs --enable-X with --disable-X instead of auto-negating: write the negated key explicitly, e.g. disable-radix-cache = true;.
A list hands every element to a single flag (--<key> a b), which is what most multi-value options of this CLI take. The few that instead expect a repeated flag have to be written out one value at a time.
Merged with services.llmhop.sglang-quadlet.models.<name>.settings; per-model
entries take precedence.
Type: attribute set of anything
Default:
{ }
services.llmhop.sglang-quadlet.models
Models to serve.
Each entry produces one quadlet container; the attribute name is the routing key
(advertised via --served-model-name and surfaced through both llmhop and the
optional SGL Model Gateway as the OpenAI model field).
Enabled entries are sorted by ascending port.
Type: attribute set of (submodule)
Default:
{ }
Example:
{
"qwen3-8b" = {
model = "Qwen/Qwen3-8B";
port = 19001;
settings = {
reasoning-parser = "qwen3";
tool-call-parser = "qwen3_coder";
mem-fraction-static = 0.6;
cuda-graph-max-bs = 4;
};
};
}
services.llmhop.sglang-quadlet.models.<name>.enable
Whether to enable serving of model ‹name›.
Type: boolean
Default:
true
Example:
true
services.llmhop.sglang-quadlet.models.<name>.devices
Devices exposed to this model’s container — passed verbatim as
Quadlet AddDevice= lines. Replaces (does not extend)
services.llmhop.sglang-quadlet.devices for this model.
Use to pin a model to specific device indices
(e.g. [ "nvidia.com/gpu=0" ]).
Type: list of string
Default:
config.services.llmhop.sglang-quadlet.devices
Example:
[
"nvidia.com/gpu=0"
]
services.llmhop.sglang-quadlet.models.<name>.digest
Immutable digest of the container image (e.g. sha256:…).
Mutually exclusive with tag.
Type: null or string
Default:
null
Example:
"sha256:a73fb0b9046fee099f7c1829d2548e6cc1740f4c2776a6855fa659ae5d0deb49"
services.llmhop.sglang-quadlet.models.<name>.environment
Additional environment variables set on this model’s service.
Merged with services.llmhop.sglang-quadlet.environment; per-model entries
take precedence.
Type: attribute set of string
Default:
{ }
services.llmhop.sglang-quadlet.models.<name>.environmentFile
File in KEY=VALUE format forwarded to this model’s service.
Loaded after services.llmhop.sglang-quadlet.environmentFile, so its entries
override global ones. Must be readable by the user systemd reads it as.
Type: null or absolute path
Default:
null
services.llmhop.sglang-quadlet.models.<name>.model
Hugging Face repo id (or local path) passed to the model server.
Type: string
Example:
"Qwen/Qwen2.5-7B-Instruct"
services.llmhop.sglang-quadlet.models.<name>.name
Canonical identifier for this model. Used for the unit name
(sglang-<name>) and as the routing key registered with llmhop
(clients select the backend by sending this value in the OpenAI
model field).
Defaults to the attribute key, so the key itself must match the required label format.
Type: string matching the pattern [[:alnum:]][[:alnum:].-]*
Default:
"‹name›"
services.llmhop.sglang-quadlet.models.<name>.port
Loopback host port forwarded to the container’s SGLang API.
Must be unique per model and must not collide with gateway.port /
gateway.metricsPort when the gateway is enabled.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
services.llmhop.sglang-quadlet.models.<name>.settings
CLI flags forwarded to the model server for this model.
true collapses to --<key>, null and empty lists are dropped, and an
attribute set is serialised to JSON.
false is dropped, since the CLI pairs --enable-X with --disable-X instead of auto-negating: write the negated key explicitly, e.g. disable-radix-cache = true;.
A list hands every element to a single flag (--<key> a b), which is what most multi-value options of this CLI take. The few that instead expect a repeated flag have to be written out one value at a time.
Merged with services.llmhop.sglang-quadlet.modelSettings; per-model entries
take precedence.
Type: attribute set of anything
Default:
{ }
services.llmhop.sglang-quadlet.models.<name>.shmSize
Size of the container’s private /dev/shm tmpfs.
PyTorch and friends use shared memory for NCCL/tensor-parallel inference;
upstream recommends 32g (or --ipc=host). A private tmpfs is preferred for
isolation: raise the value for larger models or higher tensor-parallel sizes.
Type: string
Default:
"32g"
Example:
"64g"
services.llmhop.sglang-quadlet.models.<name>.tag
Tag of the container image used for this model.
Mutually exclusive with digest.
Type: null or string
Default:
null
services.llmhop.sglang-quadlet.openFilesLimit
File descriptor limit (LimitNOFILE) applied to every sglang-quadlet systemd unit.
Increase if the server logs accept: Too many open files under concurrent load.
Type: positive integer, meaning >0
Default:
1048576
services.llmhop.sglang-quadlet.startupOrdering
Whether to chain enabled model services by ascending port during startup.
GPU-memory profiling races otherwise: two workers booting on the same device
each see it as fully free and race to claim their share, leading to OOM.
Disable only when each model pins itself to a dedicated device via its own devices.
Type: boolean
Default:
true
services.llmhop.sglang-quadlet.subGidCount
Size of the subordinate GID range mapped into every container.
Defaults to subUidCount.
Type: positive integer, meaning >0
Default:
config.services.llmhop.sglang-quadlet.subUidCount
services.llmhop.sglang-quadlet.subGidStart
First host GID of the subordinate range mapped into every container.
Defaults to subUidStart — most setups keep the UID and GID ranges aligned.
Type: unsigned integer, meaning >=0
Default:
config.services.llmhop.sglang-quadlet.subUidStart
services.llmhop.sglang-quadlet.subUidCount
Size of the subordinate UID range mapped into every container. 65536 covers the full unprivileged ID space inside the namespace.
Type: positive integer, meaning >0
Default:
65536
services.llmhop.sglang-quadlet.subUidStart
First host UID of the subordinate range mapped into every container.
Container UIDs ≥1 are mapped to subUidCount consecutive host IDs starting here.
Required — pick a value clear of NixOS system users (<1000), regular login
UIDs, and other backends’ subordinate ranges on the same host.
Type: unsigned integer, meaning >=0
Example:
300000
services.llmhop.sglang-quadlet.tag
Default tag of the container image used for models that do not set their own
tag or digest.
Type: string
Example:
"latest"
services.llmhop.sglang-quadlet.uid
Host UID assigned to services.llmhop.sglang-quadlet.user.
Required — pick a value that does not clash with other system users on the
host. It is also the inner-to-outer target of --uidmap.
Type: unsigned integer, meaning >=0
Example:
503
services.llmhop.sglang-quadlet.user
Dedicated system user owning the sglang data and cache
directories. Defaults to the backend name; override to point at a
user the deployer manages externally (in which case the matching
users.users.<name> and users.groups.<name> declarations become the
deployer’s responsibility). Container root is mapped to this user via --uidmap.
Type: string
Default:
"sglang"