From 7e55e72a58b430dfb61d291453aa75b501e291fe Mon Sep 17 00:00:00 2001 From: Mahmoud Mabrouk Date: Sun, 2 Aug 2026 12:08:17 +0200 Subject: [PATCH] docs(self-host): document the attachment limit env vars and mirror them in the env examples --- .../self-host/reference/01-configuration.mdx | 42 +++++++++++++++++++ hosting/docker-compose/ee/env.ee.dev.example | 20 +++++++++ hosting/docker-compose/ee/env.ee.gh.example | 20 +++++++++ .../docker-compose/oss/env.oss.dev.example | 20 +++++++++ hosting/docker-compose/oss/env.oss.gh.example | 20 +++++++++ 5 files changed, 122 insertions(+) diff --git a/docs/docs/self-host/reference/01-configuration.mdx b/docs/docs/self-host/reference/01-configuration.mdx index 6a16e03f50..ba2aef14ef 100644 --- a/docs/docs/self-host/reference/01-configuration.mdx +++ b/docs/docs/self-host/reference/01-configuration.mdx @@ -602,6 +602,48 @@ reachable. Enable the `ngrok` tunnel (the compose `with-tunnel` profile) or poin cross into a remote sandbox. ::: +## Agenta attachments + +Bounds the files a user can attach to an agent chat turn. The API enforces the per-file sizes +and the per-session quotas when a file is uploaded, and deletes expired attachments in a +background sweep. The runner enforces how many attachments one turn carries. Attachment bytes +live in the [store](#store-durable-object-store), so uploads fail while the store is +unconfigured. + +The chart has no dedicated values keys for these. Set them through the per-deployment env map: +`api.env.` for the API variables, `agentRunner.env.` for the runner ones. + +Read by the `api` service: + +| Env var | env.py path | What it bounds | Default | +|---|---|---|---| +| `AGENTA_ATTACHMENTS_MAX_IMAGE_BYTES` | `agenta.sessions.attachments.max_image_bytes` | Size of one image | `10485760` (10 MB) | +| `AGENTA_ATTACHMENTS_MAX_AUDIO_BYTES` | `agenta.sessions.attachments.max_audio_bytes` | Size of one audio file | `15728640` (15 MB) | +| `AGENTA_ATTACHMENTS_MAX_DOCUMENT_BYTES` | `agenta.sessions.attachments.max_document_bytes` | Size of one document | `10485760` (10 MB) | +| `AGENTA_ATTACHMENTS_MAX_OTHER_BYTES` | `agenta.sessions.attachments.max_other_bytes` | Size of one file of any other kind | `10485760` (10 MB) | +| `AGENTA_ATTACHMENTS_MAX_PER_SESSION_COUNT` | `agenta.sessions.attachments.max_per_session_count` | Stored attachments one session may hold | `1000` | +| `AGENTA_ATTACHMENTS_MAX_PER_SESSION_BYTES` | `agenta.sessions.attachments.max_per_session_bytes` | Total stored bytes across one session | `268435456` (256 MB) | +| `AGENTA_ATTACHMENTS_MAX_PENDING_PER_SESSION` | `agenta.sessions.attachments.max_pending_per_session` | Uploads in flight for one session at once | `20` | +| `AGENTA_ATTACHMENTS_PENDING_TTL_SECONDS` | `agenta.sessions.attachments.pending_ttl_seconds` | How long an unfinished upload is held before the sweep reclaims it | `900` (15 minutes) | +| `AGENTA_ATTACHMENTS_UNREFERENCED_TTL_SECONDS` | `agenta.sessions.attachments.unreferenced_ttl_seconds` | How long an uploaded attachment that no message references is kept | `86400` (24 hours) | +| `AGENTA_ATTACHMENTS_SWEEP_INTERVAL_SECONDS` | `agenta.sessions.attachments.sweep_interval_seconds` | Gap between two attachment sweeps | `3600` (1 hour) | + +The kind of a file (image, audio, document, other) comes from its media type, and an upload +over its kind's cap is rejected before anything is stored. The count and byte quotas apply to +stored attachments and are checked as each upload is claimed. The sweep runs inside the API +process, and a lock lets one replica sweep at a time. + +Read by the `runner` service: + +| Env var | env.py path | What it bounds | Default | +|---|---|---|---| +| `AGENTA_ATTACHMENTS_MAX_PER_TURN` | n/a (read by the runner) | Attachments one user turn may carry | `100` | +| `AGENTA_ATTACHMENTS_FETCH_TIMEOUT_MS` | n/a (read by the runner) | Wait for one attachment's bytes to download | `15000` (15 seconds) | + +A turn that carries more than `AGENTA_ATTACHMENTS_MAX_PER_TURN` attachments fails before the +run starts. The runner also refuses any single attachment body over 16 MB. That ceiling is +fixed in code, so raising a per-file cap above it stores files the runner cannot fetch. + ## Agenta egress | Env var | env.py path | values.yaml path | diff --git a/hosting/docker-compose/ee/env.ee.dev.example b/hosting/docker-compose/ee/env.ee.dev.example index 7609cc6d10..3c6bb3bef7 100644 --- a/hosting/docker-compose/ee/env.ee.dev.example +++ b/hosting/docker-compose/ee/env.ee.dev.example @@ -124,6 +124,26 @@ AGENTA_RUNNER_DEFAULT_SANDBOX_PROVIDER=local # cap (higher-fidelity reconstruction). Still opt-in, default off. # AGENTA_RECORDS_SMART_TRUNCATION=true +# --- Attachment limits (files attached to an agent chat turn) --- +# Per-file caps in bytes, by kind: 10 MB, except audio at 15 MB. Read by the api. +# AGENTA_ATTACHMENTS_MAX_IMAGE_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_AUDIO_BYTES=15728640 +# AGENTA_ATTACHMENTS_MAX_DOCUMENT_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_OTHER_BYTES=10485760 +# Per-session totals across stored attachments: 1000 files, 256 MB. +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_COUNT=1000 +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_BYTES=268435456 +# Uploads in flight for one session at once. +# AGENTA_ATTACHMENTS_MAX_PENDING_PER_SESSION=20 +# Seconds. An unfinished upload is reclaimed after 15 min; an attachment no message +# references is deleted after 24 h; the sweep runs hourly. +# AGENTA_ATTACHMENTS_PENDING_TTL_SECONDS=900 +# AGENTA_ATTACHMENTS_UNREFERENCED_TTL_SECONDS=86400 +# AGENTA_ATTACHMENTS_SWEEP_INTERVAL_SECONDS=3600 +# Read by the runner. Attachments per user turn, and milliseconds to fetch one attachment. +# AGENTA_ATTACHMENTS_MAX_PER_TURN=100 +# AGENTA_ATTACHMENTS_FETCH_TIMEOUT_MS=15000 + # ================================================================== # # Agenta - API # ================================================================== # diff --git a/hosting/docker-compose/ee/env.ee.gh.example b/hosting/docker-compose/ee/env.ee.gh.example index 8c3f4dee55..281d16d93f 100644 --- a/hosting/docker-compose/ee/env.ee.gh.example +++ b/hosting/docker-compose/ee/env.ee.gh.example @@ -126,6 +126,26 @@ AGENTA_RUNNER_TOKEN=replace-me # cap (higher-fidelity reconstruction). Still opt-in, default off. # AGENTA_RECORDS_SMART_TRUNCATION=true +# --- Attachment limits (files attached to an agent chat turn) --- +# Per-file caps in bytes, by kind: 10 MB, except audio at 15 MB. Read by the api. +# AGENTA_ATTACHMENTS_MAX_IMAGE_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_AUDIO_BYTES=15728640 +# AGENTA_ATTACHMENTS_MAX_DOCUMENT_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_OTHER_BYTES=10485760 +# Per-session totals across stored attachments: 1000 files, 256 MB. +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_COUNT=1000 +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_BYTES=268435456 +# Uploads in flight for one session at once. +# AGENTA_ATTACHMENTS_MAX_PENDING_PER_SESSION=20 +# Seconds. An unfinished upload is reclaimed after 15 min; an attachment no message +# references is deleted after 24 h; the sweep runs hourly. +# AGENTA_ATTACHMENTS_PENDING_TTL_SECONDS=900 +# AGENTA_ATTACHMENTS_UNREFERENCED_TTL_SECONDS=86400 +# AGENTA_ATTACHMENTS_SWEEP_INTERVAL_SECONDS=3600 +# Read by the runner. Attachments per user turn, and milliseconds to fetch one attachment. +# AGENTA_ATTACHMENTS_MAX_PER_TURN=100 +# AGENTA_ATTACHMENTS_FETCH_TIMEOUT_MS=15000 + # ================================================================== # # Agenta - API # ================================================================== # diff --git a/hosting/docker-compose/oss/env.oss.dev.example b/hosting/docker-compose/oss/env.oss.dev.example index a995d43832..52ef0c8b24 100644 --- a/hosting/docker-compose/oss/env.oss.dev.example +++ b/hosting/docker-compose/oss/env.oss.dev.example @@ -126,6 +126,26 @@ NEXT_PUBLIC_AGENT_FILE_UPLOADS=true # cap (higher-fidelity reconstruction). Still opt-in, default off. # AGENTA_RECORDS_SMART_TRUNCATION=true +# --- Attachment limits (files attached to an agent chat turn) --- +# Per-file caps in bytes, by kind: 10 MB, except audio at 15 MB. Read by the api. +# AGENTA_ATTACHMENTS_MAX_IMAGE_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_AUDIO_BYTES=15728640 +# AGENTA_ATTACHMENTS_MAX_DOCUMENT_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_OTHER_BYTES=10485760 +# Per-session totals across stored attachments: 1000 files, 256 MB. +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_COUNT=1000 +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_BYTES=268435456 +# Uploads in flight for one session at once. +# AGENTA_ATTACHMENTS_MAX_PENDING_PER_SESSION=20 +# Seconds. An unfinished upload is reclaimed after 15 min; an attachment no message +# references is deleted after 24 h; the sweep runs hourly. +# AGENTA_ATTACHMENTS_PENDING_TTL_SECONDS=900 +# AGENTA_ATTACHMENTS_UNREFERENCED_TTL_SECONDS=86400 +# AGENTA_ATTACHMENTS_SWEEP_INTERVAL_SECONDS=3600 +# Read by the runner. Attachments per user turn, and milliseconds to fetch one attachment. +# AGENTA_ATTACHMENTS_MAX_PER_TURN=100 +# AGENTA_ATTACHMENTS_FETCH_TIMEOUT_MS=15000 + # ================================================================== # # Agenta - API # ================================================================== # diff --git a/hosting/docker-compose/oss/env.oss.gh.example b/hosting/docker-compose/oss/env.oss.gh.example index 72baa8daf5..09c3c1e250 100644 --- a/hosting/docker-compose/oss/env.oss.gh.example +++ b/hosting/docker-compose/oss/env.oss.gh.example @@ -126,6 +126,26 @@ AGENTA_RUNNER_TOKEN=replace-me # cap (higher-fidelity reconstruction). Still opt-in, default off. # AGENTA_RECORDS_SMART_TRUNCATION=true +# --- Attachment limits (files attached to an agent chat turn) --- +# Per-file caps in bytes, by kind: 10 MB, except audio at 15 MB. Read by the api. +# AGENTA_ATTACHMENTS_MAX_IMAGE_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_AUDIO_BYTES=15728640 +# AGENTA_ATTACHMENTS_MAX_DOCUMENT_BYTES=10485760 +# AGENTA_ATTACHMENTS_MAX_OTHER_BYTES=10485760 +# Per-session totals across stored attachments: 1000 files, 256 MB. +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_COUNT=1000 +# AGENTA_ATTACHMENTS_MAX_PER_SESSION_BYTES=268435456 +# Uploads in flight for one session at once. +# AGENTA_ATTACHMENTS_MAX_PENDING_PER_SESSION=20 +# Seconds. An unfinished upload is reclaimed after 15 min; an attachment no message +# references is deleted after 24 h; the sweep runs hourly. +# AGENTA_ATTACHMENTS_PENDING_TTL_SECONDS=900 +# AGENTA_ATTACHMENTS_UNREFERENCED_TTL_SECONDS=86400 +# AGENTA_ATTACHMENTS_SWEEP_INTERVAL_SECONDS=3600 +# Read by the runner. Attachments per user turn, and milliseconds to fetch one attachment. +# AGENTA_ATTACHMENTS_MAX_PER_TURN=100 +# AGENTA_ATTACHMENTS_FETCH_TIMEOUT_MS=15000 + # ================================================================== # # Agenta - API # ================================================================== #