scriptorium/docs/config.md

Configuration Reference

This is the canonical reference for Scriptorium application settings and the prompt, profile, and schema files those settings select. For command syntax, see the CLI reference; for HTTP request shapes, limits, and outcomes, see the HTTP API reference.

Discovery And Precedence

Application settings are resolved in this order:

1. built-in defaults;
2. a configuration file; then
3. 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 full 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	Directory containing prompt-definition YAML. run, render, and serve require an effective value.
profile_dir	unset	Directory containing custom profile YAML. Built-in profiles remain available.
schema_dir	.	Base directory for relative JSON 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 render output format: text or json.

The three size fields must be zero or greater. The HTTP contract defines how each limit is enforced and reported. server.artifact_root configures the deployment boundary; see the HTTP API reference for request-path and containment behavior, and operations for deployment handling.

Prompt Definition Files

Prompt definitions are strict YAML files anywhere below prompt_dir. A prompt is selected by its YAML id, not by file path; nested directories are only for organization. See maintained prompt examples.

Field	Required	Meaning
id	yes	Prompt identifier.
version	yes	Prompt version.
default_profile	no	Profile used when a request omits a profile ID.
description	no	Human-readable description.
session_id	no	Go-template string rendered from request variables and sent to a compatible provider when non-empty.
inputs	no	Declared input metadata.
messages	yes	Chat-message templates.
output	yes	Output format and validation contract.

Inputs And Messages

Each inputs item has a required name and optional required, content_type, and description fields. Input names must be unique.

Each message has a required role, exactly one of content or content_file, and optional cache_control. A content_file path is relative to the prompt file. cache_control.type must be ephemeral; its optional ttl is 1h.

session_id uses the same template variables as messages. Empty rendered values are omitted. A rendered value may contain at most 256 Unicode code points.

Output Contract

Field	Required	Values or behavior
format	yes	text, markdown, or json.
validation_mode	yes	none, basic, json, or json_schema.
schema_path	for json_schema	Schema path, relative to schema_dir unless absolute.
repair_attempts	no	Integer greater than or equal to 0; omitted means 0.

Profile Definition Files

Profiles are strict YAML files anywhere below profile_dir. A profile is selected by YAML id; nested directories are organizational. See the maintained profile examples.

Field	Required	Meaning
id	yes	Profile identifier.
endpoint	yes	OpenAI-compatible base URL, including its API version path when needed.
model	yes	Provider model name.
temperature	no	Number from 0 through 2.
max_tokens	no	Integer zero or greater.
top_p	no	Number from 0 through 1.
timeout_seconds	no	Per-generation-call deadline in whole seconds; integer zero or greater.
service_tier	no	Non-empty provider-specific request tier.
reasoning_effort	no	Non-empty provider-specific reasoning setting.
api_key_env	no	Environment-variable name containing the API key.
extra_params	no	JSON-compatible provider-specific outbound request fields.

Execution defaults before profile and request overrides are temperature: 0, max_tokens: 0, top_p: 1, and timeout_seconds: 600. Profile numeric values merge by non-zero value. Request overrides preserve presence, so an explicit zero can override a profile value. For timeout_seconds, explicit request zero disables the generation deadline while retaining the caller context and the built-in client's transport cap. See the OpenAI-compatible integration contract for the complete timeout interaction.

Custom profiles take precedence over built-ins with the same ID. Invalid custom profiles are errors; they do not fall back to a built-in profile. Raw api_key is rejected. Use api_key_env, or the public Go package's request-scoped key mechanism described in the package contract.

extra_params keys must be non-empty and cannot be model, session_id, messages, temperature, max_tokens, top_p, service_tier, reasoning_effort, or response_format.

Built-In Profile Catalog

Each embedded profile uses OPENROUTER_API_KEY.

Provider	ID	Model
aion-labs	aion-2	aion-labs/aion-2.0
anthropic	claude-fable-latest	~anthropic/claude-fable-latest
anthropic	claude-haiku-latest	~anthropic/claude-haiku-latest
anthropic	claude-opus-latest	~anthropic/claude-opus-latest
anthropic	claude-sonnet-latest	~anthropic/claude-sonnet-latest
deepseek	deepseek-3-2	deepseek/deepseek-v3.2
deepseek	deepseek-4-flash	deepseek/deepseek-v4-flash
deepseek	deepseek-4-pro	deepseek/deepseek-v4-pro
google	gemini-2-flash	google/gemini-2.5-flash
google	gemini-2-flash-lite	google/gemini-2.5-flash-lite
google	gemini-2-pro	google/gemini-2.5-pro
google	gemini-3-flash-lite	google/gemini-3.1-flash-lite
google	gemini-flash-latest	~google/gemini-flash-latest
google	gemini-pro-latest	~google/gemini-pro-latest
google	gemma-4-31b	google/gemma-4-31b-it:exacto
minimax	minimax-m2	minimax/minimax-m2.5
minimax	minimax-m3	minimax/minimax-m3
mistral	mistral-large-2512	mistralai/mistral-large-2512
mistral	mistral-medium-3-5	mistralai/mistral-medium-3-5
mistral	mistral-small-3	mistralai/mistral-small-3.2-24b-instruct
mistral	mistral-small-4	mistralai/mistral-small-2603
nvidia	nemotron-3-ultra	nvidia/nemotron-3-ultra-550b-a55b
openai	gpt-5-mini	openai/gpt-5.4-mini
openai	gpt-5-nano	openai/gpt-5.4-nano

Schemas

Schemas are JSON files, normally below schema_dir. json_schema output requires a schema_path. Relative paths resolve from schema_dir; absolute paths are used directly. Referenced nested schemas use relative paths and are not discovered by basename. An unreadable or invalid schema is a runtime validation error; generated content that fails JSON or schema validation is a validation result.

Credentials

Keep secrets in environment variables. Store only an environment-variable name in api_key_env; do not place raw keys in configuration, prompt or profile files, CLI arguments, examples, or HTTP payloads.

Related References

• CLI reference
• HTTP API reference
• OpenAI-compatible outbound contract