# Download links

A report the MCP server or the REST service writes lands in the server's output directory (`output.dir`). Over HTTP, the server serves those reports itself. A result carries a link under `http.publicUrl` + `/downloads/<token>` that works for 60 minutes. MCP results carry the link twice:

- in the text the model reads
- as a `resource_link` the client can show the person

Nothing else has to run beside the server. A `render_view` with `save: false` writes no file and gets no link. Its csv or json result comes back [inline only](<https://pivotkit.eize.dev/reference/mcp/#inline-only>).

Which report gets which link depends on the source:

- A source is **open** when its policy has `"default": "show"` and no field below `show`. This must hold for the server's policy, the source's and every profile. Listing every column as `show` is not enough, since a column the data gains later would take the default.
- A source with a field at `values`, `summary` or `hide` for anyone, or whose default is not `show`, is **closed**, since its report may hold what the model was not shown.
- Data that belongs to one person counts as closed too, whatever its fields' levels. That is data sent in the request (`inline:`), a source bound to a person (a [parameter bound to a claim](<https://pivotkit.eize.dev/reference/sources/#http-claims>) or a backend's [token exchange](<https://pivotkit.eize.dev/reference/sources/#http-auth>)), and a code source you mark with [`perPerson: true`](<https://pivotkit.eize.dev/reference/sources/#code-options>).

`check-config` names, for each closed source, what makes it closed.

| Source | Caller | Link |
| --- | --- | --- |
| Open | any | A plain link anyone who has it can open until it expires (`bound: "none"`) |
| Closed | signed in over OAuth with a subject, `bind: "signIn"` | A link only that person can open, after signing in through the browser (`bound: "signIn"`) |
| Closed | `bind: "once"` (your explicit choice) | A link that works once (`bound: "once"`) |
| Closed | anything else: a static token, a token without a usable subject, `bind: "none"` | No link: the file is kept, and the result says "The report is saved on the server; ask the operator how to open it." |

Over REST, a link to a report over a closed source also needs `results: true` in the caller's policy. The caller is a program that could open the link itself, so the same rule holds as for the [file route](<https://pivotkit.eize.dev/reference/rest/#downloads>). Reports over open sources get their link without it.

Over stdio, there is no HTTP server and no link. A local server shows the file's path.

Reports can also go to a store you run (S3, Azure Blob Storage, a file service of your own). See [Upload to your store](<#upload>). The store's link then takes the place of these links, under the same rules for closed sources.

## Configuration

```
{
  "http": { "publicUrl": "https://reports.example.com" },
  "auth": { "mode": "oauth", "issuer": "https://auth.example.com/application/o/pivotkit/", "resource": "https://reports.example.com/mcp" },
  "output": {
    "dir": "reports",
    "downloads": {
      "expiresMinutes": 60,
      "key": { "env": "PIVOTKIT_DOWNLOAD_KEY" },
      "signIn": { "clientId": "pivotkit-downloads", "clientSecret": { "file": "secrets/download-client-secret" } }
    }
  }
}
```

| Key | Default | What it is |
| --- | --- | --- |
| `output.downloads.enabled` | true | The server's own links. They need HTTP and `output.dir`, and are off while `output.baseUrl` is set. `true` next to `output.baseUrl` is refused at start: choose one |
| `output.downloads.expiresMinutes` | 60 | How long a link works, 1 to 1440 minutes. A person reads the answer, opens the link and signs in within this time, so give them minutes, not seconds. `check-config` warns below 5 |
| `output.downloads.bind` | `"signIn"` with `auth.mode: "oauth"` and `signIn.clientId`, else `"none"` | How links to reports over closed sources are bound: `signIn`, `once`, or `none` (such reports get no link) |
| `output.downloads.key` | a random key per process. With a state directory, `<state>/secrets/downloads.key`, made at the first start ([made at the first start](<https://pivotkit.eize.dev/reference/rest/#first-start>)) | The link key, a secret reference (`{ "env": "NAME" }` or `{ "file": "path" }`, `"create": true` makes a missing file) of at least 32 bytes. Set it for more than one replica and for links that survive a restart. Make one with `pivotkit-server key new --for downloads --file <path>` ([tokens and keys](<https://pivotkit.eize.dev/reference/rest/#credentials>)). It is read again at most once a second, so a rotated key works without a restart, within a second. Links made with the old key stop working. Rotating without a restart needs the `{ "file": "path" }` form, since a process's environment variables do not change while it runs |
| `output.downloads.allowInsecureUrl` | false | Links under an `http://` `http.publicUrl` on a host other than loopback. Without it, the server does not start with such an address while links are on: a link is the credential, and it and its cookie would cross the network in clear text. With it, the start and `check-config` warn. Use it only on a network you trust |
| `output.downloads.signIn.clientId` | none | The browser client the person signs in with |
| `output.downloads.signIn.clientSecret` | none (a public client with PKCE) | Its secret, a secret reference, sent as HTTP Basic (or in the form where the provider only takes `client_secret_post`) |
| `output.downloads.signIn.issuer` | `auth.issuer` | May be left out. When given, it must be `auth.issuer` exactly, since a link is bound to the issuer and subject of the caller's token, so the person signs in where the client did. The server does not start otherwise, and `check-config` stops with the same message. One that differs only in spelling (a trailing slash, case in the scheme or host, a default port) says to leave it out. Another issuer points to [\#441](<https://github.com/eizedev/pivotkit/issues/441>), a sign-in with an issuer of its own for providers with one issuer per application |
| `output.downloads.signIn.scopes` | `["openid"]` | What the sign-in asks for. Must hold `openid` |
| `output.downloads.signIn.tokenUrl` | the metadata's `token_endpoint` | The token endpoint the code (and the client secret) goes to, `https://`. Without it, the metadata's endpoint must be on the issuer's own origin. Set it for a provider that keeps it on another host |

`bind: "signIn"` needs `auth.mode: "oauth"`, `http.publicUrl` with `https://` and `signIn.clientId`. The server does not start without them.

Without `http.publicUrl`:

- A server on loopback puts its own address in links (`http://127.0.0.1:3333/downloads/...`).
- A server on any other address gives no links, with a warning at start and in `check-config`, so a link never shows an internal address.

The reports that get a link are stored with the link's 22 random characters before their name (`Q3vB0rD3cE1fG9hI2jK4lM-Sales by region.pivotkit-out.xlsx`). The result's `output.name` is that stored name, and `output.filename` the name the person sees (`Sales by region.xlsx`). Reports without a link keep their names.

A report's name keeps letters, digits, spaces, `.`, `_`, `-` and parentheses. Any other character becomes `-`, accents are dropped, and the name is cut at 80 characters. For example, `Orders (fake backend)` is stored as `Orders (fake backend).pivotkit-out.xlsx`.

A key that cannot be read (a missing variable or file, shorter than 32 bytes) is a warning at start. Until it can be read, reports get no link and keep their names, and their result says to ask the operator.

## Sign-in links

A sign-in link works in three steps:

1. It opens the provider's sign-in page in the browser: the OAuth 2.1 code flow with PKCE, `state` and `nonce`.
2. The sign-in comes back to `/downloads/callback`.
3. The server sends the file only when the ID token's issuer and subject are those of the access token the report was asked with. An ID token for several audiences must name this client as `azp`.

A HEAD of the link (a link preview) answers 200 with a short page, or the link's error, and starts no sign-in.

Register at the provider:

1. A client for the browser (`signIn.clientId`), public with PKCE or confidential with a secret, with the redirect URI `https://reports.example.com/downloads/callback`. That is `http.publicUrl` + `/downloads/callback`, and `check-config` prints it.
2. Make the client resolve the same subject as the MCP client: `auth.subjectClaim` (default `sub`) is read from both tokens. Providers that give each application its own `sub` need a claim that is the same for every application, for example `oid` with Microsoft Entra ID. Check your provider's documentation. A claim such as `email` binds a link only as strongly as the provider checks that the address belongs to the person (and keeps it from moving to another account).

The link holds the person only as a keyed digest of the link's own random part, the issuer and the subject. It does not tell who it is for, and two links of one person cannot be tied to each other.

ID tokens must be signed with a key from the issuer's key set: `auth.jwksUri`, else the metadata's `jwks_uri` on the issuer's origin, as for access tokens (RS256, ES256 and the like). Tokens signed with the client secret (HS256) are not accepted. The issuer's metadata, keys and token endpoint are requested under the rules of [the server's issuer](<https://pivotkit.eize.dev/reference/mcp/#oauth>), so an issuer on a private address needs `auth.intranet: true`.

Someone signed in as another account gets 403 "You are signed in as a different account than the one that asked for this report." No session outlives the download: the short cookie that holds the sign-in under way is cleared with the answer.

## One-time links

`bind: "once"` is your explicit choice for servers without a sign-in client. A GET (or HEAD) of the link answers a short page, light or dark as the browser is set. It shows the file's name, kind and size, until when the link works (in the browser's own time zone) and a Download button. The GET never uses the link, so a chat client's link preview does not use it up. The button's POST sends the file once.

After the click the page says "Downloaded once. You can repeat it for 2 minutes, in this browser." That browser may repeat the download for two minutes, and its page says until when. Any other browser gets 409 at once, on the GET too, without a button: "This link was already used. If you downloaded the report earlier, look in the downloads of the browser you used. Otherwise ask whoever made the report to make it again."

The POST must come from the link's own page. Its `Origin` is `http.publicUrl`'s origin: the page is served with `Referrer-Policy: same-origin`, so the browser names it. A POST with `Origin: null` and `Sec-Fetch-Site: same-origin` is accepted too.

Anyone who sees a one-time link can use it once, and an assistant with a browser or a code tool can use it before the person does. `check-config` warns of that. Use `signIn` where it matters.

The server keeps which links were used, and which sign-ins came back, in `.pivotkit-downloads/` in the output directory:

- For a sign-in, it keeps its `state`, so a callback replayed with the cookie from before it is refused.
- It makes one file per link or sign-in, exclusively, so replicas sharing the directory agree.
- At most 20 sign-ins a minute from one address write such a file. Over that, the page asks to wait. Behind a proxy, set `http.trustProxy`, or every person counts as the proxy's one address.
- The files go once their link or sign-in expired. They are swept every ten minutes, and on a one-time download.
- Each file is written whole and then hard-linked to its name, so the output directory's file system must support hard links. Local disks and NFS do. Some network or object-store mounts do not, and a one-time download there answers 500.

## What a result holds

```
"output": {
  "name": "Q3vB0rD3cE1fG9hI2jK4lM-Sales by region.pivotkit-out.xlsx",
  "filename": "Sales by region.xlsx",
  "url": "https://reports.example.com/downloads/eyJ2IjoxLC...Q.k3Jx...",
  "expiresAt": "2026-11-15T09:00:00Z",
  "bound": "signIn",
  "note": "Open the link in your browser and sign in; it works for 60 minutes.",
  "format": "xlsx",
  "mediaType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}
```

`url`, `expiresAt` and `bound` are there only when a link was given. After its text, the MCP tool result adds a [resource link](<https://modelcontextprotocol.io/specification/2026-07-28/server/tools>) (Tool Result, Resource Links):

```
{ "type": "resource_link", "uri": "https://reports.example.com/downloads/eyJ2...", "name": "Sales by region.xlsx", "title": "Sales by region", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "annotations": { "audience": ["user"] } }
```

It carries `size` only for a report the assistant was shown in full. `audience` is a hint to the client, not a protection: the binding is. The resource link goes only to clients that send `MCP-Protocol-Version` 2025-06-18 or later, the revision that brought resource links. Older clients get the link in the result's JSON alone. The result's `message` names the file, not the address. The address is `output.url`.

## Answers

A browser gets a short page with a title and heading of its own for each answer. Where the server failed (status 500 or more), the page also shows the request's id. A program that asks for JSON (`Accept: application/json`) gets a problem document like the [REST service's](<https://pivotkit.eize.dev/reference/rest/#errors>), with `requestId`. A person quotes the id to the operator. The operator finds it on the request's log line where there is one: its `download` line, or the debug line of a link that does not exist.

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such link: unknown, cut off, or signed with another key (all the same answer) |
| 410 | `LINK_EXPIRED` | The link expired, or its report was removed (`output.maxFiles`, `output.maxMb`, `output.maxAgeDays`) before it did |
| 409 | `LINK_USED` | A one-time link that was used |
| 403 | `LINK_NOT_YOURS` | Signed in as another account than the one that asked |
| 403 | `FORBIDDEN_ORIGIN`, `FORBIDDEN_HOST` | A one-time link's POST from another page (`FORBIDDEN_ORIGIN`). A `Host` the server does not answer to (`FORBIDDEN_HOST`) |
| 400 | `SIGN_IN_FAILED` | The sign-in did not complete. The page tells three cases apart. Cancelled or refused at the provider: "Not signed in". No sign-in of this browser under way, as after a reload, a tab left open for more than 10 minutes or a callback opened in another browser: "Sign-in page out of date". The ID token not valid: "Sign-in failed". Each says to open the download link once more |
| 503 | `SIGN_IN_NOT_READY` | The server has not loaded the sign-in issuer's metadata yet (`Retry-After`) |

Every answer carries these headers:

- `Cache-Control: no-store`
- `Referrer-Policy: no-referrer` (`same-origin` on a one-time link's page)
- `X-Robots-Tag: noindex`
- `X-Content-Type-Options: nosniff`
- `Cross-Origin-Resource-Policy: same-origin`

A file also carries `Content-Security-Policy: sandbox; default-src 'none'` and `Content-Disposition: attachment`. A page carries `default-src 'none'`, with only its own style and the button's script allowed by their hashes (`style-src`, `script-src`), `form-action 'self'` and `frame-ancestors 'none'`.

Ranges are not served. A download request takes a body of at most 1 KiB.

## Upload to your store

With `output.upload`, a report is written to `output.dir` and then uploaded to a store you name. The result shows the store's link. You configure the store. A caller cannot name an address.

```
{
  "output": {
    "dir": "reports",
    "upload": {
      "presign": {
        "url": "https://store.example.com/presign",
        "headers": { "authorization": { "prefix": "Bearer ", "value": { "env": "STORE_TOKEN" } } },
        "uploadUrl": "/uploadUrl",
        "uploadHeaders": "/headers",
        "link": "/downloadUrl",
        "expiresAt": "/expiresAt",
        "allowOrigins": ["https://bucket.store.example.com"]
      },
      "linkOrigins": ["https://files.example.com"],
      "maxBytes": 52428800
    }
  }
}
```

Here pivotkit sends `POST https://store.example.com/presign` with the `authorization` header and the JSON `{ "filename": "Sales by region.xlsx", "mediaType": "...", "bytes": 18234, "sha256": "<hex>" }`. For a `bind: "signIn"` store, it adds `"subject"` (below).

`filename` is the report's stored name without its mark: spaces and parentheses kept, other special characters replaced by `-`. A caller can choose it, so treat it as untrusted text. Never use it unchecked as an object key or a path.

A presign service you run answers, for example:

```
{
  "uploadUrl": "https://bucket.store.example.com/reports/7f3a.xlsx?X-Amz-Signature=...",
  "headers": { "x-amz-server-side-encryption": "AES256" },
  "downloadUrl": "https://files.example.com/reports/7f3a.xlsx?sig=...",
  "expiresAt": "2026-11-16T08:00:00Z"
}
```

pivotkit then sends the file with `PUT` to `uploadUrl`, with `content-type`, `content-length` and the answer's `headers`. It shows `downloadUrl` as `output.url`, with `expiresAt`. Your credentials go to the presign address only, never to `uploadUrl`.

Without a presign service, give an address template:

- `{id}` is random and required, so every report gets an address of its own that cannot be guessed from its name.
- `{name}` is the report's name as letters, digits, `.`, `_` and `-` (at most 80 characters).
- `{format}` is its format.

```
"upload": {
  "url": "https://store.example.com/reports/{id}/{name}.{format}",
  "headers": { "authorization": { "prefix": "Bearer ", "value": { "file": "secrets/store-token" } } }
}
```

A `PUT` there makes the address itself the link. If the address has a query, `link` is required, since a query may hold a signature. With `"method": "POST"`, `link` says where the answer names the stored report: a JSON Pointer (`"/url"`) or `"header:location"`.

| Key | Default | What it is |
| --- | --- | --- |
| `output.upload.url` | none | An `https://` address template with `{id}` (required), `{name}` and `{format}` in its path or query. Use `presign` instead for a presign service |
| `output.upload.headers` | none | With `url`: headers sent to the store. A value is a text, or `{ "prefix": "Bearer ", "value": <secret reference> }`. `authorization`, `cookie` and names with `key`, `token`, `secret`, `auth` or `pass` take a secret reference only |
| `output.upload.link` | the address (`PUT` to an address without a query) | With `url`: a JSON Pointer into the store's answer, or `"header:location"`. Required for `POST` and for an address with a query. A query may hold a signature, such as a SAS token, which is never shown |
| `output.upload.expiresAt` | none | With `url`: a JSON Pointer to the link's expiry in the store's answer |
| `output.upload.presign.url` | none | The `https://` address of your presign service |
| `output.upload.presign.headers` | none | Headers sent to the presign service only, as `output.upload.headers` |
| `output.upload.presign.uploadUrl`, `.link` | none | JSON Pointers to the address to upload to and to the link, in the presign answer |
| `output.upload.presign.uploadHeaders`, `.expiresAt` | none | JSON Pointers to headers for the upload (an object of texts) and to the link's expiry |
| `output.upload.presign.allowOrigins` | the presign address's origin | The origins `uploadUrl` may have (`https://bucket.store.example.com`) |
| `output.upload.linkOrigins` | the origin of `url` or `presign.url` | The origins a link may have |
| `output.upload.method` | `"PUT"` | `PUT` or `POST` for the upload |
| `output.upload.timeMs` | 30000 | Waiting for a slot, presign and upload together, 1000 to 600000 ms |
| `output.upload.maxBytes` | `output.maxMb` | A larger report is not uploaded (`UPLOAD_FAILED`) |
| `output.upload.keepLocal` | true | Keep the report in `output.dir` too. With `false`, it is removed once the store answered 2xx and the link was checked |
| `output.upload.bind` | `"none"` | What the store's links do, as you declare it. pivotkit does not check it. The values are `none` (anyone with the link), `once`, or `signIn` (the store checks the person) |
| `output.upload.intranet` | false | The store may be on a loopback or private address |

`output.upload` needs `output.dir` and cannot be combined with `output.baseUrl`.

Which reports go to the store:

| Source | `bind` | Delivery |
| --- | --- | --- |
| Open | any | Uploaded, with the store's link (`bound` is `bind`) |
| Closed | `once` | Uploaded, with the store's link. Over REST only for a caller with `results: true` |
| Closed | `signIn` | Uploaded for a caller signed in with an issuer and subject, with the store's link. Over REST only with `results: true`. A caller without a subject gets the server's own delivery |
| Closed | `none` | Not uploaded: a store whose links anyone can open never gets such a report. The server's own links apply (a sign-in link where configured), else no link |

Schedule drafts are not uploaded: the host approves them in `output.dir`.

With `bind: "signIn"`, the presign request carries `subject`. It is an HMAC of the caller's issuer and subject under a key derived from `output.downloads.key` for this purpose alone. It is never the subject itself, and never a value a sign-in link holds. The presign service can use it to scope the object to the person and check it when they open the link.

- The value is the same for one person across reports, so the store can tell which reports belong to the same person.
- A program signed in with client credentials (a service account) has a subject too, usually its client. Its reports are bound to that client, so only a sign-in as the same service account opens them.
- Over stdio, or when the key cannot be read, no `subject` is sent.
- Without `output.downloads.key`, the server uses a random key per process, so the value changes on every restart and differs between replicas, and `check-config` warns of it.
- A `signIn` link is only as strong as the store's own access control. pivotkit declares the binding, it does not verify it.

What is checked:

- Every request goes through the same guarded fetch as [HTTP sources](<https://pivotkit.eize.dev/reference/sources/#http>): `https://` only, no redirects followed, cloud metadata and link-local addresses never, loopback and private addresses only with `intranet`.
- `uploadUrl` must be `https://` and on `allowOrigins`.
- The presign service may not ask for `host`, `content-length`, `content-type`, `content-encoding`, `expect`, `authorization`, `cookie`, `proxy-*`, `x-forwarded-*`, `forwarded` or connection headers, nor for line breaks in a value.
- A link must be `https://`, on `linkOrigins`, without a user name or password or control characters, and at most 2048 characters.
- Answers are read up to 64 KiB.
- At most two uploads run at once, and 32 wait for a slot. One more fails at once, retryable. The file is streamed from disk.
- A `PUT` is tried once more after a dropped connection or a 502, 503 or 504 while time is left. A `POST`, the presign request among them, never is.

When an upload fails, the caller gets `UPLOAD_FAILED` (502) with a fixed text, the request id and `retryable` ([REST](<https://pivotkit.eize.dev/reference/rest/#error-upload-failed>), [MCP](<https://pivotkit.eize.dev/reference/mcp/#errors>)). The report stays in `output.dir`, with `keepLocal: false` until it is cleaned up.

What went wrong is on the log only. The line `upload failed` names the request id and one of the codes below. It never names an address, a header or what the store answered, since presigned addresses and links are credentials. The caller never sees the code, since it would describe your store's setup.

| Code | Meaning | What to check |
| --- | --- | --- |
| `TOO_LARGE` | The report is larger than `maxBytes` | `output.upload.maxBytes`, `output.maxMb` |
| `SECRET` | A header's secret cannot be read | The variable or file the header names; `check-config` says which |
| `TIMEOUT` | `timeMs` passed (waiting for a slot, presign and upload), or 32 uploads were already waiting | The store's speed, `timeMs`, how many reports are made at once |
| `PRESIGN_<status>` (`PRESIGN_403`, `PRESIGN_503`) | The presign service answered with this status | Its credentials (4xx), its health (5xx) |
| `PRESIGN_ANSWER` | The presign answer is not a JSON object | The presign service |
| `PRESIGN_<fetch code>` | The presign request failed: `REFUSED_ADDRESS`, `IP_LITERAL`, `NETWORK`, `REDIRECT`, `TOO_LARGE` (answer over 64 KiB), `BAD_ENCODING` | Its address, `intranet`, the service's answer |
| `UPLOAD_URL_<problem>` | The answer's `uploadUrl` was not used: `MISSING`, `LENGTH` (over 8192 characters), `CHARS` (control characters), `PARSE`, `SCHEME` (not `https://`), `USERINFO`, `ORIGIN` (not on `presign.allowOrigins`) | `presign.uploadUrl` (the pointer), `presign.allowOrigins` |
| `UPLOAD_HEADERS` | The answer's upload headers hold a refused name, a line break, or more than 20 entries | The presign service |
| `STORE_<status>` (`STORE_403`, `STORE_503`) | The store answered the upload with this status (a PUT after 502, 503 or 504 was tried twice) | The store's permissions (4xx), its health (5xx) |
| `STORE_<fetch code>` | The upload failed: `REFUSED_ADDRESS` (a metadata, loopback or private address without `intranet`), `IP_LITERAL`, `NETWORK`, `REDIRECT`, `BAD_BODY`, ... | The store's address, `intranet` |
| `STORE_ANSWER` | The store's answer has no JSON where `link` points into it | `output.upload.link`, the store |
| `LINK_<problem>` | The link was not shown: `MISSING`, `LENGTH` (over 2048 characters), `CHARS`, `PARSE`, `SCHEME`, `USERINFO`, `ORIGIN` (not on `linkOrigins`) | `link` (the pointer), `linkOrigins` |

`LINK_<problem>` and `STORE_ANSWER` come after the upload. The store then holds the report, with no link given out for it. pivotkit does not delete it there, since it may not have the right to. Let the store's own retention remove such objects.

`check-config` prints an `Upload:` section: the target (without its query), which sources' reports go there, and where each header's secret comes from. Two cases are a `PROBLEM` the server starts with:

- a header secret it cannot read
- a target that resolves to an address uploads refuse: an IP address, a metadata address, or a loopback or private one without `intranet`

Every upload fails until it is fixed ([reading check-config](<https://pivotkit.eize.dev/reference/rest/#check-config>)).

## Behind a proxy

Behind a proxy:

- Route `/downloads/` to the service besides `/mcp` and `/api/v1/`.
- Keep the `Host` header, or add the proxy's name to `http.allowHosts`.
- Set `http.publicUrl` to the address people open.

The token is in the link's path, and proxies and browsers keep paths in their logs and history. That is why plain links go only to reports over open sources. Keep proxy logs of `/downloads/` short, or leave the path out of them.

The server's own log names a download's binding, outcome and request id, never its token. With [`audit.subject`](<https://pivotkit.eize.dev/reference/mcp/#logging>) on, a sign-in link's line also names the person who signed in, as a call's line does. That is who got the file, or who was refused with `LINK_NOT_YOURS`. A link that does not exist is on the debug log only (`--log debug`), so a scan does not fill the log.

With more than one replica, set `output.downloads.key` (the same on every replica) and give them one output directory (a ReadWriteMany volume), or run one replica. See [the container](<https://pivotkit.eize.dev/reference/container/index.md>) and [Kubernetes](<https://pivotkit.eize.dev/getting-started/kubernetes/index.md>).

`output.baseUrl` (your own web server for the directory) is the alternative to these links. It gives an address only to reports over open sources. A report over a closed source (data per person included) carries no `url`, since anyone with the address could open a report whose fields were withheld from the model, or another person's data. Such an address works as long as the file is there, 30 days by default (`output.maxAgeDays`).

Reports stay in the output directory after their link expired, until `output.maxFiles`, `output.maxMb` or `output.maxAgeDays` remove them. `output.maxAgeDays` is 30 by default: the server deletes reports older than 30 days at start and every hour. `output.maxAgeDays: 0` keeps them with no age limit. A schedule draft that waits for approval (`status` `"draft"`) stays until the host or you remove it. The default does not apply where the output directory holds the configuration or a source, template or token file. `check-config` warns under `Retention:` when you set 0 while closed sources or data sent in requests are on.

Waiting drafts never expire. They count against the drafts cap (half of `output.maxFiles`, 500 by default) and against `output.maxMb`, and the server never deletes them to make room. Once the directory is full of them, the server refuses new drafts, and renders too when only drafts are left, until a person approves or removes drafts. So approve or reject drafts by changing their `status`, or remove them. A host may also delete or move a draft instead of rewriting its `status`. A draft file that cannot be read or parsed, is over 1 MiB, or has no `status` that is a string counts as waiting.

`check-config` prints a `Delivery:` section: where links point, which sources get which link, the redirect URI to register, where the key and the sign-in client's secret come from, and the warnings. A key or client secret it cannot read is a `PROBLEM` the server starts with. Until it is fixed, reports get no links, or download links (signed in) fail after the person signs in.
