1. Enable OAuth 2.0 in your app’s authentication settings in the Developer Console. Copy its Client ID and, for a Web App, Automated App or Bot, its Client Secret. These are different from the app’s API Key and API Secret.

2. Use a separate OAuth 2.0 sign-in flow to sign in as the account you want to track and approve your app. XFlog does not provide this initial sign-in flow.

3. Request these permissions to cover all current XFlog features:

   tweet.read users.read follows.read follows.write like.read offline.access
   

   offline.access is needed to receive a refresh token. follows.write allows the optional Follow/Unfollow feature; like.read is needed for likes. Granting them does not enable those features in XFlog—choose what to use in Profile. See X’s permission guide.

4. Save the returned access token and refresh token in the settings listed above. If an older token lacks a permission, approve the app again with the updated permissions; refreshing it does not add permissions.

The console’s Access Token and Secret pair is OAuth 1.0a. It is not the OAuth 2.0 access/refresh pair used here. Changing the app’s general Read/Write setting alone does not grant OAuth 2.0 permissions to an existing token.

X user access tokens normally expire after about two hours. With the required refresh token and client settings, XFlog renews access when needed and saves the latest token pair privately in the history database. Docker and service restarts reuse that saved pair; .env is not rewritten.

Renewal does not start paused tracking, recover missed events or guarantee uninterrupted access. If X revokes access, rejects renewal, or renewal cannot be saved safely, XFlog shows an error and keeps your history. Approve the app again, replace both user tokens in .env, then apply the environment changes.

• Keep the database and its backups private: they contain saved credentials as well as history.
• After deleting the database or restoring an older backup, obtain a fresh access/refresh pair before starting. An older refresh token may no longer work.
• Use each token pair with one renewing installation. Another installation renewing the same pair can invalidate it.
• Profile lists settings needed by the currently enabled features; it is not a complete renewal checklist. Check all the live-setup settings above even if Profile shows no missing settings.

The user ID is the permanent number identifying an X profile. It stays the same if the person changes their @handle; it is not your developer app ID. An app bearer token identifies the app, so it cannot tell XFlog which person is “me.”

Leave X_USER_ID blank for automatic identification. At each startup XFlog makes one GET /2/users/me request using your user token. This can cost X credits even while tracking is paused. If it fails, tracking stays stopped and the error appears in the UI and logs; XFlog does not guess the account or rewrite .env.

Setting X_USER_ID skips that startup lookup. It must match the account that owns your user token; entering someone else’s ID does not authorize access to their private activity.

If you need to look up an ID manually, export your credentials and run:

xflog user-id @yourhandle  # Uses X_APP_BEARER_TOKEN
xflog user-id --me         # Uses X_USER_ACCESS_TOKEN

From a checkout, load .env explicitly:

uv run --no-sync --env-file .env xflog user-id @yourhandle

For a Docker Compose installation:

docker compose run --rm --no-deps xflog xflog user-id @yourhandle

Each command makes one user lookup, which can cost credits. It prints the ID without starting tracking or changing settings. Replace the handle with --me in either example to identify the supplied user token’s account. The command uses that access token as supplied; it does not renew it.

Release images are available at ghcr.io/aatbit/xflog:v1.0.0 for Linux AMD64 and ARM64. From a checkout with your private .env configured, run:

docker compose -f compose.yaml -f compose.registry.yaml up -d --no-build --pull always

This uses the same localhost port, security settings and saved history as the normal Compose setup. Keep both -f options when managing this installation. To upgrade, set XFLOG_IMAGE_TAG in .env to the new version tag and run the command again. Back up your history first. The interactive installer continues to build from source.

Download, inspect, then run:

curl -fsSL https://raw.githubusercontent.com/aatbit/xflog/main/install.sh -o install-xflog.sh
less install-xflog.sh
bash install-xflog.sh

Run the installer again and enter your existing installation folder.

• Check for updates (check) reports app and installer changes separately without changing your installation. Docker need not be running. It can offer to run the updated installer first; a script saved elsewhere stays untouched. If an app update is available, it prints the update command.
• Update: choose your install type and folder. Back up history first. Existing .env values, including blanks, and custom Docker network settings are kept; missing settings get defaults. Older installations are not prompted for new credentials during an update; add any missing renewal settings from the setup checklist to .env and apply the changes. The installer asks before restarting and stops if you have edited the app’s source files.
• Uninstall: pause tracking in the UI first, then choose the same install type and folder. Files, settings and history remain by default. Deleting history or .env requires typing DELETE at a separate prompt for each. Shared networks and X tokens are left alone. Update can reactivate a retained installation.

Saved renewal tokens stay with the history database. Deleting only .env keeps that saved copy; revoke the app’s access in X if you want to disconnect permanently.

Restarting can resume tracking if it was previously on. Pause first if you want it to stay stopped.

• Docker restarts XFlog with Docker unless explicitly stopped. Make sure Docker starts at boot. You can join an existing HTTPS-proxy network; XFlog also keeps its own private network.
• Native Linux creates a separate Python environment and xflog.service user service. Startup without logging in may need OS administrator approval. Python needs venv/ensurepip; the installer does not install system packages.
• Native history defaults to ~/.local/share/xflog/data/history.sqlite3; Docker uses a persistent volume.
• Checks and updates use main. For another branch, tag or commit, download the script and run XFLOG_REF=<ref> bash install-xflog.sh. Checks compare file contents, not version numbers; an older source can also show differences. README-only changes do not count as app updates.
• docker compose down keeps history; docker compose down -v deletes it.
• Remove a stale .xflog-maintenance.lock only after checking that no updater or uninstaller is still running.

Open a person’s details, then Interaction history. XFlog saves new interactions in its database while tracking runs; it cannot recover earlier interactions. The choices cover your account’s activity, including people outside your follower log. Outgoing replies and quotes can be linked to someone only when X supplies their ID or the referenced post.

Threads stay unloaded until you press Load thread · X reads. XFlog saves a dated copy; reopening it uses the database. Load more requests another page and Refresh checks X again. These requests need X search access and credits; a thread can contain other participants’ posts and may be incomplete.

Enabled interactions also appear in the constellation and journal, including people with no recorded follow event. The open app checks its local database every 10 seconds and updates the timeline and open interaction history automatically. New posts received by tracking are added to matching saved threads without another X request. Full threads are still loaded only when you ask: unseen replies, edits or deletions need a new X read. Cached posts remain when tracking is turned off and can be outdated.

Resolve names & handles in Profile is optional and off by default. Enable it to fill missing display names and @handles using X user lookups. X can charge per profile, even when several IDs share one request. XFlog checks each new person once, saves the result in SQLite and reuses it across the constellation, journal and HUD. It requests only identity fields, not extra grouping data. Profiles supplied with events are reused first, without a lookup. To retry unavailable profiles, switch this option off and on again; successful cached profiles are kept. Names are not checked repeatedly for changes, but later event-supplied profiles can update them.

Your browser may ask for notification permission when you save. Alerts need localhost or HTTPS and permission in each browser/device. If blocked or unsupported, in-app notices still work. Neither works after the page is closed. Changing only notifications does not change the events requested from X.

If saving shows a warning, follow it before assuming your change is active. If choices were saved but could not be applied on X, fix the access or disk problem and save again. If they could not be saved, make your choices again after fixing the problem.

• Ambient motion controls light trails and shooting stars; Motion speed ranges from 0.25× to 2×. Neither changes recording speed. Your device’s reduced-motion setting is respected.
• The clock button selects 1h, 6h, 12h, 24h, 3d, 7d, 30d or 90d for totals, hourly rates and Growth ratio. Hover or keyboard-focus a reading’s label for help. Paid-subscriber readings show new subscribers and expirations.
• Growth ratio is gains divided by losses: 7 follows and 2 unfollows gives 3.5. A dash means no ratio can be calculated, such as when there are no losses.
• Changes compare the previous equal-length period. Green means more gains or fewer losses; red means the reverse. New means the previous period had no activity.
• Readings use the full saved log and the time XFlog received events, regardless of zoom, filters or groups. They are recorded changes, not your current follower total.
• The timeline updates automatically from saved records; notification settings do not control these updates. Your zoom and selected person are preserved. Follow/unfollow readings count only audience changes, not interactions. Workspace → Connection history shows interruptions; earlier activity and events missed during gaps cannot be reconstructed. Explore demo uses sample data.

Zoom out to see groups in Constellation. Journal uses collapsible sections; one person can appear in multiple sections. Groups cover the history you have loaded, so older records can add people or change what you see.

Account size, age, verification and location use only details delivered with new events while enabled. Old missing details stay Unknown; turning a group off keeps saved history. Profile facts describe the recorded event, not a live profile check. When space allows, enabled Verification, Account size and Account age add facts to the selected-person readout. Known verified accounts get a checkmark beside their name in Constellation and the readout when Verification is enabled.

First appearance does not mean first on X. Followed again needs a recorded unfollow followed by a follow; gaps can hide that sequence. Location is profile text, not a verified address: London, UK and London, Ontario stay separate. Missing or unusable labels stay Unknown; XFlog does not guess where someone lives.

Enable Allow Follow/Unfollow in Profile and save only if you want the extra API usage. XFlog verifies the token’s account, checks the selected person when an action button can be shown, and checks again before an action. While scrolling, the highlight and readout update locally; the relationship check waits until movement settles. XFlog does not download your following list or poll relationships in the background. Recent checks are kept in a small temporary cache, so returning to someone is fast. Selecting someone after five minutes can refresh the check without hiding the last result. A slow check times out with a Retry button; it does not pause tracking.

Retry only checks the relationship; a failed write is not automatically repeated. Pending requests and blocked accounts must be managed on X. The offline demo cannot perform actions.

Turn the option off and save to stop further checks/actions; an action already sent may still complete. Following someone does not add an incoming follower event to your log.

For Docker, run from the installation folder:

docker compose up -d --force-recreate

This keeps history and loads the new values. docker compose restart does not load changed environment settings.

For an installer-managed native service, run as its owner:

systemctl --user restart xflog.service

For manual Python runs, stop and relaunch with the updated environment. Restarting can resume tracking if it was previously on.

Without XFLOG_ENV_FILE, Profile says no path was provided. Follow the complete live-setup checklist; Profile’s missing-settings list does not check every renewal setting.

The installer gives .env owner-only permissions (0600), but it is not encrypted; administrators can read it.

This example runs Caddy directly on the same server as XFlog. Caddy handles HTTPS and forwards visitors to XFlog’s private local port.

1. Point your domain at the server

Add an A record such as xf pointing to the server’s public IPv4 address. An optional AAAA record must reach the same server over IPv6. Allow ports 80 and 443 through both server and hosting-provider firewalls; keep port 7860 private. Caddy obtains and renews the certificate when DNS and these ports are ready. See Caddy’s HTTPS guide.

2. Set the public address and password in .env

XFLOG_ORIGIN=https://xf.example.com
XFLOG_ADMIN_PASSWORD="replace-with-your-own-long-password"

Use your own domain and a password following the password rules. Follow the address rules and apply the .env changes.

3. Set up Caddy

Install Caddy for your Linux distribution. With its standard Linux service, add this block to /etc/caddy/Caddyfile, keeping existing sites:

xf.example.com {
    reverse_proxy 127.0.0.1:7860
}

Use your domain and replace 7860 if you chose another local port. Validate and load it:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl enable --now caddy
sudo systemctl reload caddy

These commands assume Caddy’s standard Linux service; see its service guide for other setups.

4. Open your HTTPS address

Visit your domain and enter username xflog and the password from .env. No X sign-in callback URL is needed.

• Proxy in Docker: join the same trusted network and forward to http://xflog:7860; Caddy uses reverse_proxy xflog:7860. In a container, 127.0.0.1 means the proxy itself. Keep XFlog private and use the same public origin/password. See Caddy’s Docker guide.
• Site/HTTPS won’t open: check DNS, ports 80/443 and whether another web server is using them.
• 502 Bad Gateway: check XFlog is running and the proxy address/port matches. For Docker, run docker compose ps and docker compose logs --tail=50 xflog from its installation folder.
• Login/settings fail: use the exact address in XFLOG_ORIGIN. A different proxy must preserve the original Host and Authorization headers.

Use python -m pip install --upgrade xflog or uv lock --upgrade-package xflog followed by uv sync. Keep the [ui] extra in your pip command if you use the browser app. Stop XFlog and back up history before upgrading, then restart it with the same settings.

For unreleased development code, use python -m pip install "xflog @ git+https://github.com/aatbit/xflog.git@main". Prefer a released version for normal use.

CoreConfig needs only a database path and your X settings. It ignores browser origin, port and password settings. Supply values directly or use CoreConfig.from_env(); this reads the process environment, not an .env file.

import asyncio
from xflog import CoreConfig, Runtime

async def main():
    async with Runtime(CoreConfig.from_env()) as xf:
        page = await xf.store.history(xf.config.user_id, {"limit": 25})
        for event in page["events"]:
            print(event["name"], event["kind"])

asyncio.run(main())

A fresh database leaves tracking paused. With the live credentials configured and user_id blank, entering the context first makes one X user read to identify the user token’s account. The resolved ID is available as xf.config.user_id; the input configuration and .env stay unchanged. An existing database keeps its saved Start/Pause choice: entering the context can resume collection. Closing cancels local work and closes the database and HTTP client; it does not pause future starts or remove X subscriptions. Use await xf.collector.stop() to pause explicitly. The same feature costs apply to library callers.

Create a fresh Runtime for each context; instances are single-use. Both library and browser entry points reject a second runtime for the same database or app token. These are host-local locks for the same OS user. Containers or separate machines need shared ownership coordination; they must not independently consume the same developer app's stream. For automatic renewal, use the complete live setup. CoreConfig.from_env() reads these settings; direct configuration uses user_refresh_token, client_id and, for a confidential OAuth client, client_secret. Library callers may omit renewal settings and supply fresh access tokens themselves. Private features still need a user token with the right permissions; the installer’s stricter requirements do not change the library API.

The context returns Runtime. These services are available inside it:

For threads, import ThreadOptions from xflog. Its required sequence comes from a saved interaction. action="cached" reads locally; "open" uses the saved copy if available, otherwise requires accepted_costs=True before X reads. "refresh" and "more" also need that consent and the current checked_at value, so stale requests cannot repeat a paid refresh. offset pages through saved posts. Interaction tracking must be enabled before loading from X.

Handle these errors at your application's boundary:

• ValueError: invalid configuration or ThreadOptions values.
• RuntimeBusyError (a SetupError): another runtime owns the app or database; it has not been started or displaced.
• RuntimeError: a Runtime was entered more than once.
• SetupError: missing access, invalid saved state, disabled feature or missing thread-read consent. Its message explains the problem.
• ProviderError: rejected X requests in the transport layer; status is the HTTP status and delay the bounded retry delay in seconds. Feature services can translate these to SetupError.
• httpx.HTTPError, sqlite3.Error or OSError: network or local storage failure. Cleanup still runs when context entry or the body fails, including cancellation. Background collection reports its failures through state and message.

CoreConfig, Runtime, ThreadOptions, SetupError, RuntimeBusyError and ProviderError are exported from xflog. Lower-level modules remain grouped by feature:

• xflog.tracking: X transport, event parsing, collection and follow actions.
• xflog.history: saved events, statistics, filters and demo data.
• xflog.interactions: interaction parsing, saved conversations and thread loading.
• xflog.audience_groups: the existing grouping registry.
• xflog.web: HTTP request models and browser mounting.

xflog.app.create_app remains the self-hosted entry point, using xflog.config.Config for its additional browser settings. Its runtime is available as app.state.runtime; Runtime.lifespan(app) is the ASGI adapter for the same async context.

To run the full development suite from a checkout, use uv sync --extra ui --extra dev then uv run --no-sync pytest. To check the SDK without web packages, create a separate environment, install the base package plus pytest and pytest-asyncio, then run python -m pytest tests/test_runtime.py tests/test_identity.py tests/test_cli.py. No tests make live X requests.

1. Update the version in pyproject.toml, run uv lock, and update the image version in compose.registry.yaml. Merge the passing release PR into main.
2. Tag that commit, for example git tag v1.0.0, then git push origin v1.0.0.
3. Actions repeats the checks and verifies the tag matches the package version and belongs to main. It builds and checks the Python packages, publishes them to PyPI, and builds the version-tagged AMD64/ARM64 image on GHCR. Once both publications succeed, it creates a GitHub release with package downloads and automatically generated change notes.

PyPI uses Trusted Publishing from this repository’s release.yml workflow and pypi environment; no long-lived PyPI token is stored in GitHub. Actions are pinned to full commit hashes, with Dependabot checking for updates. If a job fails, inspect it and rerun the failed jobs; do not reuse a published version for different files. Changing a version tag does not replace files already published to PyPI.