docs(self-host): document the attachment limit env vars

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.<NAME>` for the API variables, `agentRunner.env.<NAME>` 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 |

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
 # ================================================================== #

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
 # ================================================================== #

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
 # ================================================================== #

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
 # ================================================================== #