Skip to main content
Glama

Change instance settings

set_instance_settings
DestructiveIdempotent

Update admin-only instance settings without restarting; changes apply across processes within seconds and are audited. Pass only keys to change, with validation and current state returned.

Instructions

Admins only: change instance settings without a restart; every process applies them within seconds and the change is audited. Pass only the keys to change; null returns a key to the environment's value; an empty string clears an optional one (URLs, captcha). Validated as a whole (a captcha provider needs both keys; email verification needs an email driver). Returns the same state as get_instance_settings.

Input Schema

NameRequiredDescriptionDefault
TERMS_URLNoTerms of service link shown on the sign-up form; empty = none.
CATALOG_URLNoWhere the Reelsaw catalog manifest (sounds, icons, stickers) is fetched from, hourly; the starter pack bundled with Reelsaw is used until a newer one arrives.
PRIVACY_URLNoPrivacy policy link shown on the sign-up form; empty = none.
SIGNUP_MODENoWho may sign up: open (anyone, right for a public instance with email confirmation), approval (new accounts wait for an admin; a private box) or closed (nobody). The first account is always the admin.
UPDATE_CHECKNoAsk GitHub for the latest release and tell admins when a newer Reelsaw exists. Only the request leaves the machine.
GIPHY_API_KEYNoGiphy API key: enables GIFs and stickers in Browse. Stored encrypted; empty = provider hidden.
KLIPY_API_KEYNoKlipy API key: enables GIF search in Browse (experimental). Stored encrypted; empty = provider hidden.
MAX_UPLOAD_MBNoLargest accepted file upload, in MB.
REFINE_SCENESNoScan the video for on-screen text (burned-in captions, watermarks, slides) during refine. On by default; off closes the ceiling (projects opt out via refineScenes). Shot cuts are always detected.
STALL_MINUTESNoA running job with no progress for this long is reported as stalled (log and UI).
DISFLUENCY_LLMNoModel pass on top of rule-based disfluency detection. Off by default. Ignored when disfluency removal is off. Turn on so projects may opt in via disfluencyLlm.
HEALTH_DETAILSNoInclude machine numbers in GET /api/health for anonymous callers (private networks only). Admins always get them.
MAX_STORAGE_MBNoMB of sources, uploads, renders and intros/outros an account may keep (deleted items count until they are deleted forever). 0 = unlimited.
PEXELS_API_KEYNoPexels API key (free): enables stock photos and portrait videos in Browse. Stored encrypted; empty = provider hidden.
WATERMARK_TEXTNoThe watermark text, e.g. your site name.
ICONIFY_API_URLNoIconify API used for icon search; the public one by default, or your own self-hosted instance (https).
PIXABAY_API_KEYNoPixabay API key (free): enables photos, illustrations, vectors and videos in Browse. Stored encrypted; empty = provider hidden.
CAPTCHA_PROVIDERNoBot protection on sign-up, sign-in and password reset: cloudflare-turnstile, google-recaptcha or hcaptcha; empty = off. Needs both keys.
CAPTCHA_SITE_KEYNoPublic captcha key the browser widget uses; empty = unset.
FREESOUND_API_KEYNoFreesound API key (free): enables sound effects in Browse. Stored encrypted; empty = provider hidden.
OPENVERSE_ENABLEDNoShow Openverse (Creative Commons images and audio, no key) in Browse. Off by default until you have checked its limits for your use.
CAPTCHA_SECRET_KEYNoSecret captcha key the server verifies with; stored encrypted, never shown again; empty = unset.
DISFLUENCY_REMOVALNoDetect fillers, repetitions and false starts after transcription. Off by default; turn on so projects may opt in via refineDisfluency.
MAX_SOURCE_FILE_MBNoLargest file a link source may download (yt-dlp --max-filesize), in MB.
CLIP_RETENTION_DAYSNoDelete rendered clip files this many days after rendering; the clip stays and can be re-rendered. 0 = keep forever.
MEDIA_LINK_TTL_DAYSNoShare links last this many days unless the owner picks less.
SCRATCH_CACHE_HOURSNoWith an S3 store, drop a worker's local copies of the sources and rendered clips of finished projects after this many idle hours; a job pulls them back from the bucket when it needs them, and a worker short of disk drops the least recently used ones first. 0 = keep them on the worker. The local store needs nothing: scratch and store are the same file.
STEP_RETENTION_DAYSNoDrop the saved checkpoints (finding-moments windows) of a finished project this many days after it last changed; a Retry sooner than that reuses them. 0 = keep forever.
EVENT_RETENTION_DAYSNoPrune project events older than this; each project keeps its run skeleton. 0 = keep forever.
WATERMARK_NON_ADMINSNoBurn a small watermark into the clips of accounts that are not admins. A paid plan removes it, and an admin can switch it per user on the Users page.
MAX_PROJECTS_PER_USERNoProjects an account may keep. 0 = unlimited. Admins can override per user on the Users page.
MAX_REQUESTS_PER_HOURNoChanges an account may make per hour. 0 = unlimited.
MAX_WEBHOOKS_PER_USERNoWebhook endpoints an account may add. 0 = unlimited. Admins can override per user on the Users page.
SOURCE_RETENTION_DAYSNoDelete stored source videos this many days after upload; the project stays and Retry re-fetches. 0 = keep forever.
TRANSCRIPT_CORRECTIONNoAfter transcription, fix misheard names with the language model. On by default; off closes the ceiling so no project runs it (projects opt out via refineEntities).
DELETED_RETENTION_DAYSNoDeleted projects and replaced clips stay restorable this long, then rows and files go. 0 = keep forever.
MAX_LIVE_JOBS_PER_USERNoQueued plus running jobs an account's own requests may add to. 0 = unlimited.
MAX_RERENDERS_PER_HOURNoRe-renders, hand-made clips and re-runs (re-analyze, refine) an account may ask for per hour. 0 = unlimited.
MEDIA_LINK_ALLOW_NEVERNoOwners may make a share link that never expires (they can still revoke it).
BLOCK_DISPOSABLE_EMAILSNoRefuse sign-ups from known temporary-address domains (a vendored list of about 120k domains).
DECISION_RETENTION_DAYSNoPrune users' recorded decisions (accepts, rejects, edits Reelsaw learns from) older than this. They outlive deleted projects until then. 0 = keep forever.
MAX_REQUESTS_PER_MINUTENoChanges (API mutations, MCP tool calls) an account may make per minute. 0 = unlimited. Admins can override per user on the Users page.
LLM_CALL_TIMEOUT_SECONDSNoLongest one model call may take (all its HTTP attempts together) before its step is stopped and retried. 0 = auto: 120 s for a hosted model, 600 s for a self-hosted one, and for a self-hosted transcription at least twice the chunk's audio length. Time spent waiting for a provider slot does not count. A slow CPU-only model may need more.
LLM_USAGE_RETENTION_DAYSNoPrune model and transcription usage rows older than this. 0 = keep forever.
ALLOW_PRIVATE_SOURCE_URLSNoLet link sources point at LAN or loopback hosts (a NAS). Off, they are blocked (SSRF guard).
MAX_NEW_PROJECTS_PER_HOURNoProjects an account may create per hour. 0 = unlimited.
MEDIA_LINK_RETENTION_DAYSNoDelete revoked and expired share links this many days after they stopped working. 0 = keep forever.
ADMIN_EVENT_RETENTION_DAYSNoPrune the admin event log after this many days. 0 = keep forever.
ALLOW_PRIVATE_WEBHOOK_URLSNoLet webhook URLs point at LAN or loopback hosts (a self-hosted n8n next to Reelsaw), over http too. Off, they must be public https (SSRF guard).
MAX_SIGNUPS_PER_IP_PER_DAYNoAccounts one network address may create per day. 0 = unlimited. Needs TRUST_PROXY behind a reverse proxy.
MAX_SOURCE_MINUTES_PER_DAYNoMinutes of source video an account may add per day (UTC). 0 = unlimited.
REQUIRE_EMAIL_VERIFICATIONNoNew users must click the verification link before they can sign in. The link works for 24 hours and is single-use; an expired one offers a new send. Needs an email driver in .env.
STAGE_IDLE_TIMEOUT_MINUTESNoA stage made of checkpointed steps (finding moments) is stopped when no step has finished for this long; Retry continues where it stopped. 0 = auto: 1.5 times the model call timeout.
MAX_SOURCE_MINUTES_PER_MONTHNoMinutes of source video an account may add per period: its billing period when it has a plan, else the calendar month (UTC). 0 = unlimited.
WEBHOOK_DELIVERY_RETENTION_DAYSNoDelete webhook delivery log rows older than this. 0 = keep forever.
EVENT_PROJECT_DONE_READY_EMAIL_DELAY_MINUTESNoMinutes to wait after the first project in a batch finishes before emailing that the clips are ready, so several projects land in one note. Sent only when an email driver is set and the account has not come back since those projects finished. A project that finishes while a note is already waiting joins that note.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.32.0
    • addedInput schema / properties / EVENT_PROJECT_DONE_READY_EMAIL_DELAY_MINUTES
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 180,
      +      "minimum": 1,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Minutes to wait after the first project in a batch finishes before emailing that the clips are ready, so several projects land in one note. Sent only when an email driver is set and the account has not come back since those projects finished. A project that finishes while a note is already waiting joins that note."
      +}
  2. Changed6 schema fields changedv0.31.0
    • addedInput schema / properties / ALLOW_PRIVATE_WEBHOOK_URLS
      Added value: +{
      +  "description": "Let webhook URLs point at LAN or loopback hosts (a self-hosted n8n next to Reelsaw), over http too. Off, they must be public https (SSRF guard).",
      +  "type": [
      +    "boolean",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / MAX_WEBHOOKS_PER_USER
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Webhook endpoints an account may add. 0 = unlimited. Admins can override per user on the Users page."
      +}
    • addedInput schema / properties / MEDIA_LINK_ALLOW_NEVER
      Added value: +{
      +  "description": "Owners may make a share link that never expires (they can still revoke it).",
      +  "type": [
      +    "boolean",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / MEDIA_LINK_RETENTION_DAYS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Delete revoked and expired share links this many days after they stopped working. 0 = keep forever."
      +}
    • addedInput schema / properties / MEDIA_LINK_TTL_DAYS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 3650,
      +      "minimum": 1,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Share links last this many days unless the owner picks less."
      +}
    • addedInput schema / properties / WEBHOOK_DELIVERY_RETENTION_DAYS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Delete webhook delivery log rows older than this. 0 = keep forever."
      +}
  3. Changed2 schema fields changedv0.28.1
    • addedInput schema / properties / DECISION_RETENTION_DAYS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Prune users' recorded decisions (accepts, rejects, edits Reelsaw learns from) older than this. They outlive deleted projects until then. 0 = keep forever."
      +}
    • changedInput schema / properties / LLM_CALL_TIMEOUT_SECONDS / description
      Previous value: -"Longest one model call may take (all its HTTP attempts together) before its step is stopped and retried. 0 = auto: 120 s for a hosted model, 600 s for a self-hosted one. A slow CPU-only model may need more."New value: +"Longest one model call may take (all its HTTP attempts together) before its step is stopped and retried. 0 = auto: 120 s for a hosted model, 600 s for a self-hosted one, and for a self-hosted transcription at least twice the chunk's audio length. Time spent waiting for a provider slot does not count. A slow CPU-only model may need more."
  4. Changed6 schema fields changedv0.26.3
    • addedInput schema / properties / LLM_CALL_TIMEOUT_SECONDS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 86400,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Longest one model call may take (all its HTTP attempts together) before its step is stopped and retried. 0 = auto: 120 s for a hosted model, 600 s for a self-hosted one. A slow CPU-only model may need more."
      +}
    • changedInput schema / properties / MAX_RERENDERS_PER_HOUR / description
      Previous value: -"Re-renders and hand-made clips an account may ask for per hour. 0 = unlimited."New value: +"Re-renders, hand-made clips and re-runs (re-analyze, refine) an account may ask for per hour. 0 = unlimited."
    • changedInput schema / properties / MAX_STORAGE_MB / description
      Previous value: -"MB of sources, uploads, renders and intros/outros an account may keep. 0 = unlimited."New value: +"MB of sources, uploads, renders and intros/outros an account may keep (deleted items count until they are deleted forever). 0 = unlimited."
    • addedInput schema / properties / SCRATCH_CACHE_HOURS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "With an S3 store, drop a worker's local copies of the sources and rendered clips of finished projects after this many idle hours; a job pulls them back from the bucket when it needs them, and a worker short of disk drops the least recently used ones first. 0 = keep them on the worker. The local store needs nothing: scratch and store are the same file."
      +}
    • addedInput schema / properties / STAGE_IDLE_TIMEOUT_MINUTES
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 1440,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "A stage made of checkpointed steps (finding moments) is stopped when no step has finished for this long; Retry continues where it stopped. 0 = auto: 1.5 times the model call timeout."
      +}
    • addedInput schema / properties / STEP_RETENTION_DAYS
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Drop the saved checkpoints (finding-moments windows) of a finished project this many days after it last changed; a Retry sooner than that reuses them. 0 = keep forever."
      +}
  5. Changed2 schema fields changedv0.23.0
    • changedInput schema / properties / REFINE_SCENES / description
      Previous value: -"Detect scene cuts and on-screen text during refine. Off by default; turn on so projects may opt in via refineScenes."New value: +"Scan the video for on-screen text (burned-in captions, watermarks, slides) during refine. On by default; off closes the ceiling (projects opt out via refineScenes). Shot cuts are always detected."
    • changedInput schema / properties / TRANSCRIPT_CORRECTION / description
      Previous value: -"After transcription, fix misheard names with the language model. Off by default (ceiling closed); turn on so projects may opt in via refineEntities."New value: +"After transcription, fix misheard names with the language model. On by default; off closes the ceiling so no project runs it (projects opt out via refineEntities)."
  6. Changed10 schema fields changedv0.19.1
    • addedInput schema / properties / CATALOG_URL
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "uri",
      +      "maxLength": 500,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Where the Reelsaw catalog manifest (sounds, icons, stickers) is fetched from, hourly; the starter pack bundled with Reelsaw is used until a newer one arrives."
      +}
    • addedInput schema / properties / FREESOUND_API_KEY
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 200,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Freesound API key (free): enables sound effects in Browse. Stored encrypted; empty = provider hidden."
      +}
    • addedInput schema / properties / GIPHY_API_KEY
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 200,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Giphy API key: enables GIFs and stickers in Browse. Stored encrypted; empty = provider hidden."
      +}
    • addedInput schema / properties / ICONIFY_API_URL
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "uri",
      +      "maxLength": 500,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Iconify API used for icon search; the public one by default, or your own self-hosted instance (https)."
      +}
    • addedInput schema / properties / KLIPY_API_KEY
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 200,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Klipy API key: enables GIF search in Browse (experimental). Stored encrypted; empty = provider hidden."
      +}
    • addedInput schema / properties / OPENVERSE_ENABLED
      Added value: +{
      +  "description": "Show Openverse (Creative Commons images and audio, no key) in Browse. Off by default until you have checked its limits for your use.",
      +  "type": [
      +    "boolean",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / PEXELS_API_KEY
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 200,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Pexels API key (free): enables stock photos and portrait videos in Browse. Stored encrypted; empty = provider hidden."
      +}
    • addedInput schema / properties / PIXABAY_API_KEY
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 200,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Pixabay API key (free): enables photos, illustrations, vectors and videos in Browse. Stored encrypted; empty = provider hidden."
      +}
    • changedInput schema / properties / REQUIRE_EMAIL_VERIFICATION / description
      Previous value: -"New users must click the verification link before they can sign in. Needs an email driver in .env."New value: +"New users must click the verification link before they can sign in. The link works for 24 hours and is single-use; an expired one offers a new send. Needs an email driver in .env."
    • changedInput schema / properties / SIGNUP_MODE / description
      Previous value: -"Who may sign up: open (anyone), approval (new accounts wait for an admin) or closed (nobody). The first account is always the admin."New value: +"Who may sign up: open (anyone, right for a public instance with email confirmation), approval (new accounts wait for an admin; a private box) or closed (nobody). The first account is always the admin."
  7. Addedv0.17.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that changes take effect within seconds across processes without a restart, that the change is audited, and that validation happens as a whole so one bad key rejects the batch. It does not explain the destructiveHint=true consequence (e.g. that clearing a URL or key silently disables a feature) or whether a rejected batch leaves any state changed, and no rollback path is described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Roughly sixty words across four front-loaded sentences: permissions and effect first, then the update convention, then validation rules, then return shape. No sentence is redundant with the schema and nothing is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 56 parameters and no output schema, the description handles the cross-cutting semantics well and points to get_instance_settings for the returned state. However, for a destructive, audited bulk mutation it omits what an agent most needs at this complexity: whether a failed whole-batch validation changes nothing, and whether there is any way to revert an accidental reset to defaults.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the per-key meanings are documented. The description still adds real meaning the schema cannot: the tri-state convention (omit / null / empty string) and cross-field validation constraints such as a captcha provider needing both keys and email verification needing an email driver.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('change instance settings') plus scope ('Admins only') and effect ('without a restart'). It also names the sibling get_instance_settings as the read counterpart whose state is returned, so an agent can tell the pair apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete invocation rules: pass only the keys to change, use null to reset to the environment value, use an empty string to clear optional values. It does not explicitly exclude per-user settings handled by siblings such as set_email_preferences or set_learning, so the when-not guidance is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.