Configuration
Marigold reads two files:
| File | Where | What it holds |
|---|---|---|
marigold-host.toml |
on the host | how this machine runs the platform: compose files, storage, database, registries, network, resource limits |
marigold.toml |
in each application | what the application is and runs; see Building |
An application config that sets a host section is rejected. Both files
may set [environment]; the application’s values win per key.
Every setting goes through these two files. The CLI validates
marigold-host.toml against one model (cli/host_config.py) and hands
the platform’s containers the result as environment variables, so no
container reads configuration from anywhere else. The tables below are
generated from that model.
Where it is read from
First match wins:
--host-config PATHon the command line$MARIGOLD_HOST_CONFIG, which must exist when setmarigold-host.tomlin the current directory~/.marigold/marigold-host.toml
With no file, every value is its default. Because of rule 3, changing
directory can change which file is used; set MARIGOLD_HOST_CONFIG or
pass --host-config in scripts.
marigold config path # the marigold-host.toml in use
marigold config show [name] # every resolved value, marked [host] or [default]
Example
[platform]
compose_files = ["core", "cpu", "gpu"]
[storage]
location = "/data/marigold"
[[registry]]
url = "https://examples.marigold.run/"
name = "examples" # optional
[network]
bind = "0.0.0.0" # reachable from other machines
[resources.worker]
memory = "48g" # below the host's total memory
Sections
Unknown sections and keys are errors.
[platform]
| Key | Default | Description |
|---|---|---|
compose_files |
["core", "cpu"] |
Platform compose files. Add “gpu” for an NVIDIA worker: [“core”, “cpu”, “gpu”]. |
tag |
unset | Image tag for the platform images. Unset means the installed CLI’s version. |
log_level |
"INFO" |
Log level for the worker and application instances. |
idle_timeout |
120 |
Seconds the worker keeps a model loaded with an empty queue. 0 never unloads. |
[storage]
| Key | Default | Description |
|---|---|---|
location |
"~/.marigold/cache" |
The cache directory: models, the platform database, outputs and installed applications. A local path or a mounted network share. |
outputs |
"fs" |
Where images, audio and video outputs are stored: files under the cache, S3, or Azure Blob Storage. |
bucket |
unset | s3: the bucket, which must already exist. |
endpoint |
unset | s3: the endpoint of an S3-compatible service. Unset means AWS S3. |
region |
unset | s3: the region, passed as AWS_DEFAULT_REGION. Unset leaves the shell’s AWS_DEFAULT_REGION. |
container |
unset | azure: the blob container, which must already exist. |
[database]
| Key | Default | Description |
|---|---|---|
url |
unset | An external Postgres connection string. Unset means the platform’s own Postgres, built from the keys below. |
name |
"marigold" |
Platform Postgres: database name. |
user |
"marigold" |
Platform Postgres: user. |
password |
"marigold" |
Platform Postgres: password. |
[[registry]]
Registries searched for applications, in file order. The first registry listing a name supplies it.
| Key | Default | Description |
|---|---|---|
url |
required | The registry’s address: http:// or https://. |
name |
unset | A local name for the registry, as with git remotes. Recorded only; nothing resolves by it yet. |
Default: none.
[network]
| Key | Default | Description |
|---|---|---|
bind |
"127.0.0.1" |
Host address the API and Open WebUI publish on. “0.0.0.0” publishes on every interface, so other machines can reach them. |
api_port |
8000 |
Host port for the API. |
webui_port |
3000 |
Host port for Open WebUI, when an application adds it. |
[resources]
[resources.executor]
Each application instance.
| Key | Default | Description |
|---|---|---|
memory |
"4g" |
Memory limit, such as ‘4g’. Unset means no limit. |
cpus |
2.0 |
CPU limit, in cores. Unset means no limit. |
pids |
512 |
Process and thread limit. Unset means no limit. |
[resources.worker]
The inference worker. Model weights load through host memory, so set memory below the host’s total.
| Key | Default | Description |
|---|---|---|
memory |
unset | Memory limit, such as ‘4g’. Unset means no limit. |
cpus |
unset | CPU limit, in cores. Unset means no limit. |
pids |
unset | Process and thread limit. Unset means no limit. |
shm |
"2g" |
Shared memory (/dev/shm) for the worker, used by PyTorch. |
[resources.api]
The API.
| Key | Default | Description |
|---|---|---|
memory |
"1g" |
Memory limit, such as ‘4g’. Unset means no limit. |
cpus |
unset | CPU limit, in cores. Unset means no limit. |
pids |
unset | Process and thread limit. Unset means no limit. |
[resources.postgres]
The platform Postgres.
| Key | Default | Description |
|---|---|---|
memory |
"1g" |
Memory limit, such as ‘4g’. Unset means no limit. |
cpus |
unset | CPU limit, in cores. Unset means no limit. |
pids |
unset | Process and thread limit. Unset means no limit. |
[resources.webui]
Open WebUI, when an application adds it.
| Key | Default | Description |
|---|---|---|
memory |
"2g" |
Memory limit, such as ‘4g’. Unset means no limit. |
cpus |
unset | CPU limit, in cores. Unset means no limit. |
pids |
unset | Process and thread limit. Unset means no limit. |
[environment]
Variables forwarded to every service. An application’s [environment] wins per key.
Default: none.
Secrets
Credentials never go in marigold-host.toml. The CLI passes these
from the shell environment to the containers that need them:
| Variable | Used for |
|---|---|
HF_TOKEN |
gated or private Hugging Face models, during cache populate |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION |
outputs = "s3" |
AZURE_STORAGE_ACCOUNT |
outputs = "azure", with a managed identity |
AZURE_STORAGE_CONNECTION_STRING |
outputs = "azure", with a connection string |
Output storage
Images, audio and video are stored as objects and served by the API at
GET /output/{mode}/{task}/{message_id}/{field}. [storage] outputs
chooses the store:
[storage]
outputs = "fs" # files under the cache's data/outputs
# any S3-compatible service
outputs = "s3"
bucket = "marigold" # must already exist
endpoint = "http://minio:9000" # unset means AWS S3
region = "eu-west-2"
# Azure Blob Storage
outputs = "azure"
container = "marigold" # must already exist
For several hosts sharing one store, see Deployment.
Resource limits
Every container runs with the limits in [resources], so one service
cannot take the whole machine. An application instance gets 4 GB of
memory, 2 CPUs and 512 processes by default. The worker has no memory
limit by default, because model sizes vary with the host: set
[resources.worker] memory below the host’s total so a model too large
for the machine fails inside its container, leaving the host running.
Application instances also run hardened: no Linux capabilities, no
privilege escalation, a read-only root filesystem with a writable
/tmp, and the host user’s identity, so the files an instance writes
to /outputs belong to whoever runs marigold.
Authentication
Marigold has no authentication of its own. The caller is identified by
an optional X-User-Id header, defaulting to local-user, and that
header is trusted as received.
On localhost or a private network this needs nothing further. To expose
the API beyond that boundary, put the deployment’s own authentication
in front of it – a reverse proxy, a cloud load balancer, an identity
provider – and have it set X-User-Id for each authenticated caller.