# Spindle configuration > Every environment variable read by spindle and cilogs, with its default. Spindle is configured by environment variables only. Durations use Go syntax (`5m`, `720h`) and lists are comma-separated. ## Role | Variable | Default | Description | | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `SPINDLE_ROLE` | `standalone` | `standalone` ingests events and runs jobs, `mill` ingests events and places jobs on executors, `executor` dials a mill and runs jobs. | | `SPINDLE_LOG_FORMAT` | `text` | Format of logs on stderr: `text` or `json`. | ## Server | Variable | Default | Description | | ------------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `SPINDLE_SERVER_HOSTNAME` | required | Public hostname. The spindle DID is `did:web:`. | | `SPINDLE_SERVER_OWNER` | required in standalone and mill | DID of the spindle owner, always an admin. | | `SPINDLE_SERVER_ADMINS` | unset | DIDs of additional admins. Each entry must be a valid DID. | | `SPINDLE_SERVER_ADMISSION` | `closed` | `closed` serves admins and the allow-list, `open` serves anyone who is not banned. | | `SPINDLE_SERVER_KEY_PATH` | required in standalone and mill | PEM file with the EC P-256 private key behind `/.well-known/did.json`. | | `SPINDLE_SERVER_LISTEN_ADDR` | `0.0.0.0:6555` | HTTP listen address. | | `SPINDLE_SERVER_METRICS_LISTEN_ADDR` | `127.0.0.1:9091` | Prometheus metrics listen address. | | `SPINDLE_SERVER_DB_PATH` | `spindle.db` | SQLite database path. Also the default `--db` of the admin subcommands. | | `SPINDLE_SERVER_REPO_DIR` | `repos` | Directory of per-repo checkouts. | | `SPINDLE_SERVER_JETSTREAM_ENDPOINT` | `wss://jetstream1.us-west.bsky.network/subscribe` | Jetstream endpoint for live events. | | `SPINDLE_SERVER_PLC_URL` | `https://plc.directory` | PLC directory for DID resolution. | | `SPINDLE_SERVER_DEV` | `false` | Development mode: allows plain HTTP and private-network addresses for knots, webhooks, clones and backfill. | | `SPINDLE_SERVER_DEV_EXTRA_HOSTS` | unset | Hostnames mapped to `host-gateway` in nixery workflow containers. | | `SPINDLE_SERVER_LOG_DIR` | `/var/log/spindle` | Directory of workflow log files. In standalone, the disk artifact store when `SPINDLE_ARTIFACT_STORES_DISK_DIR` is unset. | | `SPINDLE_SERVER_LOG_MAX_BYTES` | `33554432` | Maximum size of one workflow’s stored log, in bytes. Output past it is dropped. `0` means no cap. | | `SPINDLE_SERVER_MAX_JOB_COUNT` | `2` | Pipelines that run at once. | | `SPINDLE_SERVER_REPO_JOB_WORKERS` | `256` | Repos refreshed at once, shared between knots. Must be greater than zero. | | `SPINDLE_SERVER_NOTIFY_SLOTS` | `64` | Knot notify events processed at once, shared between knots. Must be greater than zero. | | `SPINDLE_SERVER_PRIORITY_KNOTS` | unset | Knot hosts or `did:web` DIDs that get reserved repo job workers and notify slots. | | `SPINDLE_SERVER_PRIORITY_REPO_JOB_WORKERS` | `0` | Repo job workers reserved for priority knots. `0` means a quarter of `SPINDLE_SERVER_REPO_JOB_WORKERS`. | | `SPINDLE_SERVER_PRIORITY_NOTIFY_SLOTS` | `0` | Notify slots reserved for priority knots. `0` means a quarter of `SPINDLE_SERVER_NOTIFY_SLOTS`. | | `SPINDLE_SERVER_DOCKER_SOCKET` | unset | Docker socket mounted into nixery workflow containers and set as their `DOCKER_HOST`. | | `SPINDLE_SERVER_CORS_ORIGINS` | unset | Origins allowed to call XRPC from a browser, or `*` for any. Unset disables CORS. | | `SPINDLE_SERVER_LOGS_ADDR` | unset | `host:port` of a cilogs SSH server, returned to a knot whose push scheduled a pipeline. | ## Contact and links Served by `org.tangled.spindle.describeSpindle`. | Variable | Default | Description | | -------------------------------- | ------------------------------- | ------------------------------- | | `SPINDLE_CONTACT_EMAIL` | required in standalone and mill | Operator contact email. | | `SPINDLE_LINKS_PRIVACY_POLICY` | unset | Privacy policy URL. Absolute. | | `SPINDLE_LINKS_TERMS_OF_SERVICE` | unset | Terms of service URL. Absolute. | ## Backfill | Variable | Default | Description | | ---------------------------- | --------- | ---------------------------------------------------------------------------------- | | `SPINDLE_SERVER_HYDRANT_DIR` | `hydrant` | Directory of the embedded hydrant database, its API socket and the spindle cursor. | ## Secrets | Variable | Default | Description | | ------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------- | | `SPINDLE_SERVER_SECRETS_PROVIDER` | `sqlite` | `sqlite` stores secrets in the spindle database, `openbao` uses an OpenBao Proxy. | | `SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR` | `http://127.0.0.1:8200` | OpenBao Proxy address. | | `SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT` | `spindle` | KV v2 mount. | ## Nixery engine | Variable | Default | Description | | --------------------------------------------------- | ------------------- | -------------------------------------------- | | `SPINDLE_NIXERY_PIPELINES_NIXERY` | `nixery.tangled.sh` | Nixery host that builds workflow images. | | `SPINDLE_NIXERY_PIPELINES_WORKFLOW_TIMEOUT` | `5m` | Default workflow timeout. | | `SPINDLE_NIXERY_PIPELINES_MAX_JOB_MEMORY_MB` | `6144` | Memory limit per workflow container, in MiB. | | `SPINDLE_NIXERY_PIPELINES_MAX_CONCURRENT_WORKFLOWS` | `8` | Workflow containers running at once. | ## MicroVM engine | Variable | Default | Description | | --------------------------------------------------- | --------------- | ----------------------------------------------------------------------------- | | `SPINDLE_MICROVM_PIPELINES_IMAGE_DIR` | unset | Directory of microVM images. Required by microVM workflows. | | `SPINDLE_MICROVM_PIPELINES_OVERLAY_DIR` | system temp dir | Directory of per-workflow temporary disks. | | `SPINDLE_MICROVM_PIPELINES_DEFAULT_IMAGE` | `nixos-x86_64` | Image used when a workflow sets no `image`. | | `SPINDLE_MICROVM_PIPELINES_AGENT_PORT` | `10240` | vsock port of the guest agent. | | `SPINDLE_MICROVM_PIPELINES_ENABLE_KVM` | `true` | Use KVM acceleration. | | `SPINDLE_MICROVM_PIPELINES_WORKFLOW_TIMEOUT` | `5m` | Default workflow timeout. | | `SPINDLE_MICROVM_PIPELINES_AGING_THRESHOLD` | `30s` | Queue time after which smaller requests can no longer go ahead of a workflow. | | `SPINDLE_MICROVM_PIPELINES_MAX_TOTAL_MEMORY_MIB` | `0` | Memory across all running microVMs, in MiB. `0` means unlimited. | | `SPINDLE_MICROVM_PIPELINES_MAX_TOTAL_VCPUS` | `0` | vCPUs across all running microVMs. `0` means unlimited. | | `SPINDLE_MICROVM_PIPELINES_MAX_TOTAL_DISK_MIB` | `0` | Disk across all running microVMs, in MiB. `0` means unlimited. | | `SPINDLE_MICROVM_PIPELINES_MAX_WORKFLOW_MEMORY_MIB` | `0` | Memory one workflow may request, in MiB. `0` means unlimited. | | `SPINDLE_MICROVM_PIPELINES_MAX_WORKFLOW_VCPUS` | `0` | vCPUs one workflow may request. `0` means unlimited. | | `SPINDLE_MICROVM_PIPELINES_MAX_WORKFLOW_DISK_MIB` | `0` | Disk one workflow may request, in MiB. `0` means unlimited. | ### Cgroups | Variable | Default | Description | | ------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------- | | `SPINDLE_MICROVM_PIPELINES_ENABLE_CGROUPS` | `false` | Run each workflow’s processes in a per-workflow cgroup. | | `SPINDLE_MICROVM_PIPELINES_CGROUP_PARENT` | `self` | Parent cgroup. `self` is the spindle process’s own cgroup. | | `SPINDLE_MICROVM_PIPELINES_CGROUP_PIDS_MAX` | `4096` | Process limit per workflow cgroup. | | `SPINDLE_MICROVM_PIPELINES_CGROUP_SWAP_MAX_MIB` | unset | Swap limit per workflow cgroup, in MiB. | | `SPINDLE_MICROVM_PIPELINES_CGROUP_CPU_MAX_PERCENT` | `0` | CPU quota as a percentage of one core. `0` caps each VM at its vCPU count, negative disables the limit. | | `SPINDLE_MICROVM_PIPELINES_CGROUP_IO_WEIGHT` | `0` | IO weight, 1 to 10000. `0` leaves IO unlimited. | | `SPINDLE_MICROVM_PIPELINES_CGROUP_SUPERVISOR_MEMORY_MIN_MIB` | `512` | `memory.min` of the spindle supervisor cgroup, in MiB. | ### Debug SSH | Variable | Default | Description | | --------------------------------------------------- | -------------- | ----------------------------------------------------------- | | `SPINDLE_MICROVM_PIPELINES_DEBUG_SSH_ENABLED` | `false` | Allow SSH into the VM of a failed workflow. | | `SPINDLE_MICROVM_PIPELINES_DEBUG_SSH_LISTEN_ADDR` | `0.0.0.0:2222` | Debug SSH listen address. | | `SPINDLE_MICROVM_PIPELINES_DEBUG_SSH_HOST` | unset | Host in the printed SSH command. | | `SPINDLE_MICROVM_PIPELINES_DEBUG_SSH_JUMP_HOST` | unset | Jump host in the printed SSH command. | | `SPINDLE_MICROVM_PIPELINES_DEBUG_SSH_HOST_KEY_PATH` | unset | Host private key. Unset generates one next to the database. | | `SPINDLE_MICROVM_PIPELINES_DEBUG_SSH_GRACE_PERIOD` | `5m` | Time a failed workflow’s VM stays up after failure. | ## Nix cache | Variable | Default | Description | | ------------------------------------------ | ------- | ----------------------------------------------------------- | | `SPINDLE_NIX_CACHE_READ_URLS` | unset | Binary caches microVM guests read from. | | `SPINDLE_NIX_CACHE_TRUSTED_PUBLIC_KEYS` | unset | Trusted public keys for those caches. | | `SPINDLE_NIX_CACHE_UPLOAD_URL` | unset | Binary cache that paths built in the guest are uploaded to. | | `SPINDLE_NIX_CACHE_REQUIRE_SIGNED_UPLOADS` | `false` | Require uploaded narinfos to be signed by a trusted key. | | `SPINDLE_NIX_CACHE_MAX_STAGED_MIB` | `5120` | Upload staging limit, in MiB. Must be greater than zero. | | `SPINDLE_NIX_CACHE_MAX_STAGED_OBJECTS` | `1024` | Upload staging object limit. Must be greater than zero. | ## CI cache | Variable | Default | Description | | ------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `SPINDLE_CACHE_BACKEND` | unset | `disk` or `s3`. Unset disables the cache. | | `SPINDLE_CACHE_DISK_DIR` | `cache` next to the database | Directory of the `disk` backend. | | `SPINDLE_CACHE_S3_BUCKET` | unset | Unversioned bucket of the `s3` backend. | | `SPINDLE_CACHE_S3_PREFIX` | `spindle/cache` | Key prefix in the bucket. | | `SPINDLE_CACHE_STORE_ID` | unset | Identity of a shared cache store. A mill places cached workflows only on executors with the same value; unset on a mill disables the cache. | | `SPINDLE_CACHE_RETENTION` | `720h` | Time since last use after which an entry is deleted. `0` keeps entries forever. | | `SPINDLE_CACHE_PRUNE_INTERVAL` | `1h` | Interval between prunes of expired entries. | | `SPINDLE_CACHE_MAX_BYTES_PER_OWNER` | `10737418240` | Bytes stored across all repos of one owner. `0` means unlimited. | | `SPINDLE_CACHE_MAX_ENTRIES_PER_OWNER` | `1000` | Entries across all repos of one owner. `0` means unlimited. | ## Artifact stores | Variable | Default | Description | | ----------------------------------- | ----------- | -------------------------------------------------------- | | `SPINDLE_ARTIFACT_STORES_DISK_DIR` | unset | Directory of the disk store. | | `SPINDLE_ARTIFACT_STORES_S3_BUCKET` | unset | Bucket of the S3 store. | | `SPINDLE_ARTIFACT_STORES_S3_REGION` | `us-east-1` | Region of the S3 store. | | `SPINDLE_S3_LOG_BUCKET` | unset | Deprecated alias of `SPINDLE_ARTIFACT_STORES_S3_BUCKET`. | ## Quotas | Variable | Default | Description | | ---------------------------------------------- | ------- | ------------------------------------------------------------------------- | | `SPINDLE_QUOTA_{USER,REPO}_WORKFLOWS` | `0` | Concurrent workflows. `0` means unlimited, negative is rejected. | | `SPINDLE_QUOTA_{USER,REPO}_VCPUS` | `0` | Concurrent vCPUs. `0` means unlimited, negative is rejected. | | `SPINDLE_QUOTA_{USER,REPO}_MEMORY_MIB` | `0` | Concurrent memory, in MiB. `0` means unlimited, negative is rejected. | | `SPINDLE_QUOTA_{USER,REPO}_DISK_MIB` | `0` | Concurrent disk, in MiB. `0` means unlimited, negative is rejected. | | `SPINDLE_QUOTA_{USER,REPO}_CACHE_STORAGE_MIB` | `0` | CI cache storage, in MiB. `0` means unlimited, negative is rejected. | | `SPINDLE_QUOTA_{USER,REPO}_WEBHOOKS` | `0` | Webhooks. `0` means unlimited, negative is rejected. | | `SPINDLE_QUOTA_{USER,REPO}_CI_MINUTES_MONTHLY` | `0` | CI minutes per calendar month. `0` means unlimited, negative is rejected. | ## OIDC | Variable | Default | Description | | ----------------------- | -------------- | ------------------------------------------------------------------------------ | | `SPINDLE_OIDC_ISSUER` | unset | `iss` claim of workflow ID tokens. Must be set with `SPINDLE_OIDC_KEY_PATH`. | | `SPINDLE_OIDC_KEY_PATH` | unset | PEM file with an EC P-256 private key. Must be set with `SPINDLE_OIDC_ISSUER`. | | `SPINDLE_OIDC_KEY_ID` | key thumbprint | `kid` header. Defaults to the RFC 7638 thumbprint of the key. | ## Mill and executors | Variable | Default | Role | Description | | -------------------------------------- | ------- | -------------- | --------------------------------------------------------------------------------------------------------------- | | `SPINDLE_MILL_URL` | unset | executor | Mill websocket endpoint. Required in executor, rejected in other roles. | | `SPINDLE_MILL_SHARED_SECRET` | unset | executor | Executor token for the mill. Required in executor. | | `SPINDLE_MILL_SEATS` | `4` | executor | Seats advertised to the mill. | | `SPINDLE_MILL_LABELS` | unset | executor | Capability labels advertised to the mill. | | `SPINDLE_MILL_ARTIFACT_STORE` | unset | mill, executor | Name of the artifact store shared by the mill and its executors. Optional when exactly one store is configured. | | `SPINDLE_MILL_MAX_PENDING` | `100` | mill | Pending job queue limit. | | `SPINDLE_MILL_RECONNECT_GRACE` | `45s` | mill | Reconnect window of an executor before its leases fail. | | `SPINDLE_MILL_CANCEL_ACK_TIMEOUT` | `10s` | mill | Wait for an executor to acknowledge a cancel. | | `SPINDLE_MILL_CANCEL_TEARDOWN_TIMEOUT` | `10m` | mill | Wait for a cancelled job to tear down. | | `SPINDLE_MILL_DRAIN_TIMEOUT` | `20m` | all | Drain time on shutdown. Must be greater than zero. | | `SPINDLE_MILL_JUMP_LISTEN_ADDR` | unset | mill | SSH jump listen address for debug sessions on executors. Requires `SPINDLE_MILL_JUMP_HOST_KEY_PATH`. | | `SPINDLE_MILL_JUMP_HOST_KEY_PATH` | unset | mill | Host key of the jump listener. | | `SPINDLE_MILL_DEBUG_EXECUTOR_PORT` | `2223` | mill | Executor debug SSH port that the jump host forwards to. | | `SPINDLE_MILL_MAX_JUMP_CONNECTIONS` | `128` | mill | Concurrent jump connections. Must be greater than zero when the jump listener is set. | ## Scheduled workflows | Variable | Default | Description | | ----------------------------------- | ------- | ----------------------------------------------------------------------- | | `SPINDLE_SCHEDULE_MINIMUM_INTERVAL` | `5m` | Shortest schedule interval. Must be a positive whole number of minutes. | | `SPINDLE_SCHEDULE_CONCURRENCY` | `4` | Scheduled runs started at once. Must be greater than zero. | ## cilogs | Variable | Default | Description | | ---------------------- | ----------------------- | --------------------------------------------------------------- | | `CILOGS_LISTEN_ADDR` | `0.0.0.0:3333` | SSH listen address. | | `CILOGS_HOST_KEY_PATH` | unset | Host key path, created when missing. Unset uses `./id_ed25519`. | | `CILOGS_PLC_URL` | `https://plc.directory` | PLC directory for DID resolution. | | `CILOGS_DEV` | unset | `true` allows plain HTTP and private-network addresses. | ## Telemetry | Variable | Default | Description | | ------------------------------ | --------- | -------------------------------------------------------- | | `SPINDLE_TRACING_ENDPOINT` | unset | OTLP/HTTP endpoint for traces. Unset disables tracing. | | `SPINDLE_TRACING_SERVICE_NAME` | `spindle` | Service name on traces. | | `SPINDLE_TRACING_SAMPLE_RATIO` | `1` | Sampling ratio, 0 to 1. | | `SPINDLE_TRACING_INSECURE` | `false` | Use plain HTTP to the collector. | | `SPINDLE_LOGGING_ENDPOINT` | unset | OTLP/HTTP endpoint for logs. Unset keeps logs on stderr. | | `SPINDLE_LOGGING_SERVICE_NAME` | `spindle` | Service name on logs. | | `SPINDLE_LOGGING_INSECURE` | `false` | Use plain HTTP to the collector. |