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:

  1. --host-config PATH on the command line
  2. $MARIGOLD_HOST_CONFIG, which must exist when set
  3. marigold-host.toml in the current directory
  4. ~/.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.

Source of this page on GitHub