# Receiving large Telegram files

Omnius has no default inbound attachment byte cap or cache byte cap. Downloads stream to disk, retaining only a small signature prefix in memory. Cache item-count and age eviction still apply. Authenticated admin DMs can pass an uploaded document's exact Telegram alias to `file_read` or `archive_extract`; extraction returns a destination and file manifest for subsequent inspection.

Telegram's hosted Bot API limits downloads to 20 MB. A [Local Bot API server](https://core.telegram.org/bots/api#using-a-local-bot-api-server) supports larger downloads. Omnius must use that server for polling and all Bot API methods as well as file retrieval.

## Configure the transport

Run the official [Telegram Bot API server](https://github.com/tdlib/telegram-bot-api#usage) in `--local` mode using your own Telegram API application credentials. Use a private endpoint and a shared files directory readable by Omnius. The server's absolute `file_path` must resolve to the same file in Omnius's filesystem; container deployments need matching mount paths. The server directory must not include unrelated private files.

Merge these fields into the project's `.omnius/settings.json` or global `~/.omnius/settings.json`, preserving existing settings:

```json
{
  "telegramBotApiBaseUrl": "http://127.0.0.1:8082",
  "telegramBotApiLocalFilesRoot": "/srv/telegram-bot-api"
}
```

These are example values: use the running server's actual endpoint and directory. Port 8081 on the reviewed host belongs to IPFS. Environment variables override the settings:

| Setting | Environment variable | Default |
| --- | --- | --- |
| `telegramBotApiBaseUrl` | `OMNIUS_TELEGRAM_BOT_API_BASE_URL` | `https://api.telegram.org` |
| `telegramBotApiLocalFilesRoot` | `OMNIUS_TELEGRAM_BOT_API_LOCAL_FILES_ROOT` | No local filesystem access |
| `telegramMaxAttachmentBytes` | `OMNIUS_TELEGRAM_MAX_ATTACHMENT_BYTES` | No byte cap |
| `telegramFileDownloadTimeoutMs` | `OMNIUS_TELEGRAM_FILE_DOWNLOAD_TIMEOUT_MS` | 600000 ms |

Leave the attachment limit absent for uncapped downloads. Explicit limits and timeouts must be positive integers. Increase the download timeout for slower transfers; it also applies to `getFile` while the local server obtains the file. Restart Omnius after changing transport settings. Inference endpoint settings are independent.

Before switching a running bot, stop its old poller and follow Telegram's [migration procedure](https://github.com/tdlib/telegram-bot-api#moving-a-bot-to-a-local-server), including calling the hosted server's `logOut` method before using the local endpoint. Do not run cloud and local pollers concurrently. This is a live bot migration, not a consequence of installing the source repair.

## Archive consumption and verification

`archive_extract` supports ZIP and TAR, including gzip/bzip2/xz-compressed TAR. It requires Python 3 and Linux `renameat2` support. It writes into a fresh destination within the working directory, rejects unsafe paths, links and special files, and never overwrites an existing destination. It does not execute uploaded code. There is no default extracted-byte or entry-count cap; optional `maxOutputBytes`, `maxEntries` and `timeout` arguments are available. Archive extraction is available in authenticated admin DMs under the existing filesystem-tool policy.

After publishing and migrating the bot, resend the project archive and ask Omnius to extract it and read its README. Confirm the received byte count, extraction destination/manifest, actual file read, and a delivered result. The repository regression uses a ZIP above 37 MiB through mocked Telegram download, actual cache, alias resolution, extraction and file read. That passing test does not establish live migration or delivery.
