Skip to Content
DocumentationLocal image service

Local image service

The CLI emits photograph URLs by default. The companion service makes them available to Obsidian Desktop on the same Mac. A URL names a photograph of a post you can copy a message link to: a post of a channel or a supergroup, private ones included. Private chats and basic groups have no such link and get no URL. Videos, GIFs, image documents, web previews, paid and expiring media are outside this version.

A URL is a name, not a download. Giving it writes nothing: a URL nobody opens leaves no trace. The service saves the photograph the first time someone opens the URL and serves the copy from then on, without Telegram. A post deleted before anyone opened its photographs takes them with it.

Install and start

One Homebrew Formula, octolab/tap/indexit, installs both the CLI and its service definition. They use the same binary and update together. For a new installation, run brew install --formula octolab/tap/indexit.

If you installed the previous Cask, migrate once after the Formula is published:

brew update brew uninstall --cask octolab/tap/indexit brew install --formula octolab/tap/indexit

Do not use --zap: keep your Telegram configuration and saved photographs. Then start the service and check it:

brew services start octolab/tap/indexit curl -fsS -o /dev/null http://indexit.localhost:17840/

Photograph URLs point to http://indexit.localhost:17840/. A .localhost name always means this Mac: macOS resolves it to loopback, 127.0.0.1 and ::1, without a hosts entry, sudo or any other system setup. The image service runs as your normal user and listens only on loopback, 127.0.0.1:17840 and [::1]:17840; without IPv6 it serves on 127.0.0.1 alone. Installing the package alone does not start it. Do not run sudo brew services.

The service reads the same ~/.config/indexit/.env and Telegram session as the CLI. The service ignores working-directory .env files and uses the shared config directory; explicit --env-file and INDEXIT_ENV_FILE still override it. Ordinary CLI commands retain their working-directory lookup. Sign in through the CLI before requesting an uncached photograph. No separate HTTP proxy is needed.

On the first request for a photograph, the service finds its channel by itself: a channel it found before, the CLI’s peer cache, which it only reads, your dialogs with the archive, and the channel’s cached username. If the account cannot see the channel, the URL answers 404: fetch the post on this Mac and open it again. A post or a photograph gone from Telegram, or a photograph the author replaced, answers 410: an old URL never shows another picture.

Dashboard

Open http://indexit.localhost:17840/Β  in a browser. The page shows how many photographs this Mac keeps and their size, the free space on the disk, how many requests the service answered from disk and per download, the days photographs were saved, the channels they come from and the ten latest, with links to the photograph and to its Telegram post. It updates by itself every 15 seconds while it is open.

It counts the photographs on disk, nothing else: a fetch registers nothing. It also lists what needs a look: photographs Telegram answered no longer exist, failed requests, and files in the image directory that are not photographs. /api/v1/stats returns the same numbers as JSON.

The page lists every saved photograph, so it answers only on this Mac: to an address of loopback, localhost or a .localhost name, and not through a proxy. Photograph URLs work as before. To turn the page off, set dashboard = false under [service] and restart the service.

The days come from the dates of the image files: a photograph restored from a backup counts as saved on the day it was restored. The calendar of the last 26 weeks appears once the oldest photograph is two weeks old, with a table of the same days for the keyboard and screen readers. Request counts start with v0.3.1 and cover the last 13 months. Browsers keep photographs for a year, so a view is not always a request.

Configuration

indexit service run writes ~/.config/indexit/config.toml, or $XDG_CONFIG_HOME/indexit/config.toml, next to the shared .env, when there is none: every key is there, commented out with its default. It never changes an existing file. brew services starts the service without your shell’s environment, so it uses ~/.config even if you set XDG_CONFIG_HOME; the service log names the file it wrote.

Change the URL origin

Each export carries its URLs as they were written. To write new ones with another origin, uncomment origin under [service]:

[service] origin = "http://photos.localhost:17840"

The origin is http:// or https://, a host name or an IPv4 address and an optional port, with nothing after them but an optional slash. Any .localhost name on port 17840 reaches the service as well. Another port, or a host that does not resolve to this Mac, needs your own proxy in front of the service, which keeps listening on its loopback addresses. The CLI and the service read the same file, which accepts only the keys of the template: an unknown key or a malformed value stops the command with an error naming the file and the key. Without an origin, URLs use http://indexit.localhost:17840.

With an origin outside this Mac, the dashboard is off unless you set dashboard = true: the proxy in front of the service would show it to everyone who reaches the proxy.

Share the photographs between computers

The saved photographs can live apart from the rest of the data, in a folder another computer shares, such as one in Google Drive. Uncomment images under [service] with an absolute path or one starting with ~/:

[service] images = "~/Google Drive/indexit/images"

A photograph’s path is its URL’s path under that folder: images/c<channel>/<message>/p<photo>.jpg. Another computer that runs the service with the same folder shows the same photographs by the same URLs, without asking Telegram. A photograph neither has saved is filled by whichever service is asked, if its account can see the channel. A service writes a photograph to a temporary file next to it, named for the computer, checks that it is a complete JPEG, then moves it into place, and never replaces a saved one. A conflict copy the cloud folder leaves, p… (1).jpg, is neither served nor counted.

Storage and availability

Data lives in ~/.local/share/indexit, or $XDG_DATA_HOME/indexit. INDEXIT_DATA_DIR overrides the complete directory. The photographs are in images/ of it unless images under [service] says otherwise; the locks of the downloads and the request counts stay in the data directory of each computer. stats/ holds the request counts of the dashboard, one small file a month; the service removes months older than 13. Deleting it resets the counts and nothing else. There is no automatic eviction or storage limit: disk use grows as images are read. Keep a backup if a local copy may become the only surviving photograph.

A saved image needs no Telegram session or network, and a request for it never reaches Telegram. A saved file that cannot be read answers 503 and is never downloaded again; check the image directory. A cold request waits for any running CLI Telegram operation, for at most two minutes; retry a failed request. Cached requests continue during that wait. Concurrent downloads of one photo are coalesced across processes and incomplete files are never published.

URLs contain no secret token. Any local client knowing a URL can read its image. They are not promised to work from a phone, another machine or a web page that blocks local HTTP. Clearing browser cache does not delete the saved photograph.

If Obsidian opens a note before the service is ready, failed image elements may remain visible after the service starts. Check curl -fsS -o /dev/null http://indexit.localhost:17840/, then reopen the note or switch to reading view to reload its images.

Upgrade, stop and remove

brew update brew upgrade --formula octolab/tap/indexit brew services restart octolab/tap/indexit brew services stop octolab/tap/indexit

Old URLs, configuration and saved data survive updates and restarts. To remove the Formula:

brew services stop octolab/tap/indexit brew uninstall --formula octolab/tap/indexit

Uninstall preserves the photographs. Explicitly remove files under images/ only when you intend to discard those copies, and leave your Telegram configuration alone. Deleted remote sources cannot be recovered.

Local development and Linux

go build -o ./bin/indexit . ./bin/indexit service run

Repeat --listen with a literal loopback address and port, such as --listen 127.0.0.1:8080, to replace both default addresses. Without --listen, a system without IPv6 serves on 127.0.0.1 alone.

The ordinary Linux CLI still works; automatic Linux service setup is outside this iteration. The dashboard works the same way at the address you listen on, such as http://localhost:8080/.