Telegraph-Image: A Free Image Host on Cloudflare Pages and Telegram

The pitch: your own image host, without a storage bill

Telegraph-Image describes itself as a "Free Image Hosting solution, Flickr/imgur alternative" built on Cloudflare Pages and the Telegram Bot API. The repository description makes the architecture explicit: "Using Cloudflare Pages and Telegraph." A live demo is hosted at im.gurl.eu.org.

The idea is a neat piece of arbitrage. Cloudflare Pages gives you serverless functions and, with a KV namespace, a place to store short mappings from an ID to a real URL. Telegram, which almost certainly has more spare capacity than any small image host needs, provides the actual image bytes. You upload through a web page, a Pages Function posts the file into a Telegram channel you control using a bot, the function stores the resulting link, and you get a URL back on your own domain.

None of that is free hosting in the sense of having no limits. Telegram imposes its own quota on what a channel can accept, and Cloudflare imposes its own on Pages and KV. But the cost structure is the appeal: for the volume most personal sites and small forums generate, the bill stays at zero.

Adoption is substantial. The project has roughly 4,700 stars, and strikingly, about 8,900 forks, nearly twice the star count. Forks are cheap to make and many will be people who deployed their own copy rather than contributing code back, but a fork ratio that high is still a signal about how many people run this.

The repository is not archived, and the last push recorded is July 27, 2026, a little over two months before this article was written.

The Telegraph API went away, so the design changed

The most important thing to understand about this project is that its original design no longer exists. The README opens with a callout that reframes everything else:

Since the original Telegraph API interface was closed by the official, you need to switch the upload channel to Telegram Channel. Please set `TG_Bot_Token` and `TG_Chat_ID` according to the deployment requirements in the documentation, otherwise the upload function will not work properly.

Telegraph was Telegram's old blogging tool for long-form posts, and it had a convenient anonymous image upload endpoint that many small projects leaned on. When Telegram closed it, projects built on that endpoint broke at once. Telegraph-Image's response was to route uploads through a real bot into a real channel, which requires the owner to supply credentials.

This is a genuine architectural change with real operational consequences. Before, you deployed and it worked. Now you deploy and then have to create a bot, make it an administrator of a channel, and collect two identifiers. The README's own framing is unambiguous: if you skip this, "the upload function will not work properly."

It also means the project now depends on an account you personally hold, and on a channel you personally administer. Nothing about the free tier disappears, but the zero-setup promise does.

What the deployment actually involves

The README promises "3 simple steps to have your own image hosting" and states that the only prerequisite is a Cloudflare account. There is a parenthetical caveat about deploying "without relying on Cloudflare," which points at issue 46, so self-hosting on your own infrastructure is a known open question rather than a solved feature.

Step one is to fork the repository. Step two is to deploy through Git or the Wrangler CLI, and the README is specific that this matters, linking to the Cloudflare Pages Functions documentation rather than allowing any deployment method. Step three is the one that trips people up. After the first deployment you go to the project settings, open Environment Variables, add `TG_Bot_Token` and `TG_Chat_ID`, save, and then redeploy once more.

That redeploy requirement is stated twice in different forms, and it generalizes: the documentation notes that after changing environment variables or the KV binding, you need to redeploy for the changes to take effect. Cloudflare Pages builds an environment at deploy time, so this is expected behavior for the platform rather than a quirk of this project. It is still the kind of thing that produces support questions, because a variable that visibly appears in the dashboard has not actually taken effect yet.

Once it is deployed you open the generated `pages.dev` domain and start uploading.

Getting the two Telegram credentials

The credential step is documented in enough detail to follow without leaving the README, which is more than a lot of Telegram-based projects manage.

For the token, you message the command `/newbot` to @BotFather and follow its prompts for a name and username. It replies with the token.

For the channel, you create a new Telegram channel, enter its settings, and add the bot you just made as a channel administrator so it can post. The README is clear that this step is mandatory: the environment variable table says to "ensure the TG Bot is an administrator of the channel or group."

The channel ID can then be obtained from either of two helper bots. The README lists @VersaToolsBot first, which returns your channel ID after you send it a message, and @GetTheirIDBot as an alternative.

The example values in the configuration table are worth noting for expectations. `TG_Bot_Token` looks like `123468:AAxxxGKrn5` and `TG_Chat_ID` like `-1234567`. The negative sign on the chat ID is normal, since Telegram identifies channels and supergroups with negative numbers, and people sometimes mistake it for a typo or strip it when copying.

Configuration, and the feature list it unlocks

Everything is set through environment variables in the Pages project, and the README maintains a reference table for them. Beyond the two required Telegram values, the optional set is where this becomes more than a minimal uploader.

There is a dashboard at `/admin`, guarded by `BASIC_USER` and `BASIC_PASS`. Leaving those unset gives you a dashboard without a login, which is worth understanding before you assume it is private. The public upload endpoint can be separately protected with `UPLOAD_BASIC_USER` and `UPLOAD_BASIC_PASS`.

Short links come from `ENABLE_SHORT_URLS`, which requires a bound KV namespace and returns addresses like `/file/AbC123` instead of the long filename, with `SHORT_URL_LENGTH` controlling the id length from 4 to 16 and defaulting to 6. The documentation reassures that existing long links keep working.

Image review is the most interesting corner. `MODERATION_PROVIDER` accepts `cloudflare-ai`, which the README calls recommended, `moderatecontent`, which is marked legacy, or `none`. When left unset it auto-detects, choosing `moderatecontent` if a `ModerateContentApiKey` is present and `cloudflare-ai` if an `AI` binding exists.

Two details stand out. `MODERATION_AI_MODEL` defaults to `@cf/meta/llama-3.2-11b-vision-instruct`, and the README explains that when you do not set it, a fallback chain of current vision models is tried in order so that a model being retired by Cloudflare degrades gracefully. Setting `CF_ACCOUNT_ID` and `CF_API_TOKEN` together enables live model discovery, building the chain from Cloudflare's current catalog and caching it in KV for 6 hours. That is a level of resilience thinking you rarely see in a hobby-scale project.

The table of contents also lists anti-hotlinking, R2 storage, site customization, whitelist mode, and custom domain as documented options.

Local development with Wrangler

The repository ships a `package.json` with a small set of scripts, and the dependencies list is telling. Alongside Cloudflare's wrangler and mocha, both are dev dependencies, the runtime dependencies are `@cloudflare/pages-plugin-sentry` and `@sentry/tracing`. Error reporting is a first-class part of the project rather than an afterthought.

The `start` script runs the Pages dev server locally with a KV namespace, an R2 bucket, test credentials bound inline, and local persistence:

npx wrangler pages dev ./ --kv \"img_url\" --r2 \"img_r2\" --port 8080 --binding BASIC_USER=admin --binding BASIC_PASS=123 --persist-to ./data

A second script, `start:r2`, does the same but sets `STORAGE_PROVIDER=r2` and passes the binding as a bare `BASIC_PASS=123` assignment alongside it, so the two invocations are not interchangeable. Testing is mocha for unit work, with a separate `test:e2e` script pointing at `test/e2e/homepage.js` for the homepage.

The tree itself is plain and mostly static. `index.html` is the main upload page, and the variants `index-md.html` and `index-nuxt.html` sit beside it alongside a `_nuxt/` directory. Several admin pages exist in different forms: `admin.html`, `admin-waterfall.html`, and `admin-imgtc.html` with matching stylesheets. A `functions/` directory holds the Pages Functions, and `test/` holds the test suite. Assets are minimal, just `bg.svg`, `music.svg`, and a favicon.

One thing to notice: `node_modules/` is present in the committed tree listing. That makes the repository larger than it needs to be, though a `.gitignore` is also listed, so it may reflect a working directory snapshot rather than tracked content.

Who it suits, and what to watch

Telegraph-Image is a good fit for personal blogs, small communities, and anyone who needs occasional image hosting without a vendor relationship. The setup is genuinely quick for a serverless deploy, and the optional feature set goes well past what a weekend project usually offers, particularly around image review.

The tradeoffs are equally clear. Your images live in a Telegram channel, which means their availability depends on Telegram's policies and on an account that only you control. A bot token in an environment variable is a credential that would let anyone with it post to your channel. Upload protection is available but optional, so a default deployment has a public write endpoint.

The license is CC0-1.0, the most permissive option available, which puts essentially no obstacle between you and running your own instance. Attribution is not required.

The project is genuinely active. With 4,700 stars, 25 open issues, and a push on July 27, 2026, this is not an abandoned repository. For a deployment you control end to end, the operational burden is yours, and the README is honest about which parts that includes.

Editorial conclusion

Telegraph-Image is a clever piece of infrastructure arbitrage, taking free capacity from Cloudflare and Telegram and turning it into an image host you control. It costs you a bot token and a channel, and it rewards you with a CC0 license and a feature set that goes well past the usual weekend project. Just remember that the images live in Telegram, and that the credentials protecting them are yours to manage.

Frequently asked questions

Official sources

1. cf-pages/Telegraph-Image on GitHub
2. Issues
3. License: CC0-1.0
4. Project website
5. README