6.9 KiB
Configuration Reference
This is the canonical reference for Scriptorium application settings. Prompt, profile, schema, execution-setting, built-in profile, and framework credential semantics are defined by the Promptkit v0.11.0 format reference. For command syntax, see the CLI reference; for HTTP request shapes and outcomes, see the HTTP API reference.
Discovery And Precedence
Application settings are resolved in this order:
- built-in Scriptorium defaults;
- a configuration file; then
- CLI overrides.
When --config is omitted, Scriptorium searches
/usr/local/etc/scriptorium/config.yml and then /etc/scriptorium/config.yml.
If neither exists, it uses built-in defaults. An explicit --config path must
exist and decode successfully.
The maintained minimal configuration and complete configuration are copyable examples.
Application Configuration File
Configuration is strict YAML: unknown fields are rejected. Empty string values do not override a prior value. Raw API-key fields are not accepted.
| Field | Default | Meaning |
|---|---|---|
prompt_dir |
unset | Promptkit prompt-definition source directory. run, render, and serve require an effective value. |
profile_dir |
unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
schema_dir |
. |
Promptkit schema source directory for relative schema paths. |
server.addr |
:8080 |
Address used by serve. |
server.artifact_root |
unset | Root that enables HTTP file input references. |
server.max_request_bytes |
16777216 |
Maximum encoded HTTP request-body bytes; 0 disables the limit. |
server.max_artifact_bytes |
16777216 |
Maximum HTTP file-input artifact bytes; 0 disables the limit. |
server.max_response_bytes |
16777216 |
Maximum encoded HTTP response bytes; 0 disables the limit. |
defaults.render_format |
text |
Default prepared-run output format: text or json. |
backends |
unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. |
transient_retries |
Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or null delegates to Promptkit; 0 disables additional attempts. |
The size fields must be zero or greater. The HTTP API defines how
each limit is enforced and reported. server.artifact_root configures an HTTP
deployment boundary; see operations for deployment handling.
Custom Backends
Use backends when a profile selects an application-defined backend ID:
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0
Each mapping key is the case-sensitive backend ID. endpoint is required;
api_key_env, extra_params, concurrency_limit, and queue_capacity are
optional. concurrency_limit: 0 leaves the backend unlimited. Omitting
queue_capacity lets Promptkit use its default for a limited backend, while
an explicit queue_capacity: 0 disables queueing.
Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
validates backend IDs, endpoints, environment-variable names, extra parameters,
and capacity relationships when Scriptorium constructs its engine. There are no
backend command-line overrides. Store only an environment-variable name in
api_key_env; raw API-key fields are not accepted.
Framework Source Mapping
Scriptorium passes prompt_dir, profile_dir, and schema_dir to Promptkit
when constructing its engine. Scriptorium does not redefine or independently
parse those framework file formats.
- Prompt selection, versions, message templates, inputs, output contracts, and session IDs are Promptkit contracts.
- Profile fields, numeric ranges, execution defaults, overlay precedence, built-in profiles, and credential rules are Promptkit contracts.
- Schema path behavior and generated-content validation are Promptkit contracts.
See the
tagged Promptkit format reference
for all of those definitions. The files under
examples/prompts,
examples/profiles, and
examples/schemas are maintained Scriptorium
application inputs using that tagged format.
Promptkit supplies the opt-in profile IDs promptkit-openrouter-standard and
promptkit-openrouter-auto. They can be selected as a prompt default or request
profile, and custom profile sources retain precedence. Their effective model
settings may change with a catalog upgrade; use a complete application-owned
profile when fixed settings are required. See the tagged format reference for
the maintained-profile contract.
Credentials And Outbound Behavior
Scriptorium maps --api-key-env and HTTP model.api_key_env into Promptkit
request overrides. Keep secret values in environment variables and store only
their names in configuration or framework source files. Do not place raw keys
in configuration, prompts, profiles, CLI arguments, examples, or HTTP
payloads.
An optional api_key_env whose environment value is absent or empty can result
in an unauthenticated provider request. A profile that declares credentials
required still fails as an invalid request when no credential source is
selected, and fails with ErrAPIKeyEnvMissing when its selected environment
source is absent or empty. Scriptorium never reads or emits the environment
value itself.
Unset optional provider controls are omitted from compatible provider requests.
A positive Promptkit repair_attempts budget can add provider calls, latency,
token use, and cost; see the tagged format reference for its permitted values
and validation-mode requirements.
Promptkit's built-in client makes up to two additional attempts for eligible
transient HTTP statuses by default. The application transient_retries setting
changes that budget for its constructed engine; an explicit run request
override takes precedence. This can increase latency, request count, and cost.
Each initial or repair generation has its own transient budget; an injected
client retains its own retry behavior. The tagged integration contract owns
eligibility and timing.
Promptkit's OpenAI-compatible integration contract defines outbound authentication, provider request mapping, transport limits, and timeout layering.