Help
New here? Start with using Circagraph, or look for your question among the frequently asked questions. Every topic below is also searchable.
Start here
Using CircagraphA walk through Circagraph: making a timeline, adding moments and durations, zooming from millennia to fractions of a second, and sharing it.Frequently asked questionsShort answers to common questions about Circagraph: what it is, whether it is free, accounts, where data is kept, offline use, file formats and dates.Comparison of timeline toolsCircagraph beside TimelineJS, Aeon Timeline, Chronos, Time.Graphics, Preceden, Tiki-Toki and Timeline: dates, sources, size, offline use, price.Project overviewCircagraph is a free, open-source timeline editor for exact dates at any scale, from deep time to fractions of a second, with sources on every event.
Making timelines
Timeline time presentationHow a timeline shows its times: calendar dates, numbers, units or your own format, with exact times underneath and dates before year 1.DurationsDurations: periods with a start and an end, anchored to times or to moments, with notes and metadata like moments, drawn as bands on the timeline.Entity tags and separationTags on events: short labels such as war or trade, how to add them, filter by them, and separate a timeline into tracks by tag.ViewsA view is a saved way of showing a timeline: a set of separations, with their disjoins and unions, or an event's relationships, under a title.RelationshipsRelationships link two events on a timeline, drawn as arcs, and links join events across timelines: how to add, browse and remove them.Images and copyrightImages on timelines: icons, backgrounds and a timeline's own picture are linked where they are hosted, not copied, and what the service does with them.Searching a timelineSearch the open timeline by its events' titles and notes: how matching and ranking work, and how the server stores and serves the search.Browsing, popularity and account standingHow Explore lists, searches and ranks timelines and events: established accounts, standing against spam, popularity, trends and related timelines.Comparing timelines and live viewingCompare timelines side by side or combined on one axis, keep a comparison as a public page, and see others' edits live.Timelines from filesMake a timeline from the files on your computer in the desktop app: a moment for each photo, video, recording or document, at the time you choose.Shifting and scaling timesShift or scale the times of many events at once, for good: a whole timeline or the events a separation selects, by an offset or a factor.MeasuresExact quantities that moments and durations carry, such as a cost or hours worked: declared per timeline, given per event, and added up exactly.Timeline pluginsTimeline plugins: icons, headings, backgrounds, themes, charts and fields that extend moments and durations, where they run, and how to publish them.Timeline size and platformsHow large a timeline can be: up to 200,000 moments, durations and relationships, which platform suits which size, and how the app advises you.Guest and standalone editingEditing without an account: the guest editor and the offline HTML file keep timelines in memory, and how to keep your work before closing.
Sharing and working together
Sharing timelinesShare timelines: their addresses, links, the share dialog, previews, search engines, embeds, and showing them in other pages and AI chats.Dashboard and timeline collaborationWorking on timelines together: collaborators and permissions, forks and duplicates, saving while others save, pull requests, and saved history.Reports and moderationReporting timelines and accounts, sensitive-content labels, and how a site's administrators review reports and restrict what breaks the rules.Data retention and quick deletionKeep only a timeline's recent past, for logs that keep growing; stop keeping saved history; and delete everything in a view.
Accounts and the API
Accounts, sessions and deploymentSign-in on a Circagraph server: passwords, passkeys, two-factor codes, directory sign-in, human verification, and connecting the desktop app.HTTP APIThe HTTP API that the web app, the desktop app and the command-line tools use: its OpenAPI description, how to call it, and its warnings.HTTP API referenceEvery operation of the API, who may call it, and Try it.
Running a server
Installing a serverInstall your own Circagraph server: a package for Debian, Ubuntu, Fedora, RHEL, Arch, FreeBSD, macOS or Windows, Docker Compose, Nix, or from source.Administration, storage limits and automationRun a Circagraph server: the first administrator, storage quotas, the landing page, IndexNow, page caching, terms, API keys and other operator settings.Docker deploymentRun your own Circagraph server with Docker Compose: public hosting, upgrades and backups, and email for account security.Nix and NixOSInstall Circagraph with Nix or NixOS: the flake's packages, nix-env without flakes, and the NixOS module that runs a server with PostgreSQL.Public example timelinesThe example timelines a new server can load: how to load them, the plugins and time conventions they use, and the World War II campaign comparison.Syslog to timelinesReceive syslog over UDP and TCP into timelines: each message becomes a moment, routed to timelines by rules, live, through the API.The systemd journal to timelinesFollow the systemd journal into timelines: each journal entry becomes a moment, live, routed to timelines by unit and fields, through the API.Importing log filesImport log files into timelines: syslog, Apache, nginx, JSON lines and journald exports, one moment per entry at its exact time, with its fields kept.GitHub to timelinesMirror GitHub, GitLab, Forgejo and Gitea issues, pull requests and commits into timelines, ongoing while open, by webhook or import.Boards and plans to timelinesMirror Trello, Jira, Planner, OpenProject and Microsoft Project cards, columns and Gantt plans into timelines, by webhook, polling or import.Copyright, GPLv3, and distributionsCircagraph's licence, the GNU GPL version 3: where the source and releases are, contributions, and how licence changes are handled.
How it works
Timeline and query contractHow Circagraph stores and exchanges timelines: the .ochx and .och formats, exact times, window summaries, saved history and server operations.Building and testingRun Circagraph from source: the development server, package managers, the offline file and its editions, the desktop app, tests, CI and releases.BenchmarksHow Circagraph's speed holds up as timelines grow: measured times for saves, searches, downloads and interactions on each storage backend.