Astrolabe Documentation العربية GitHub

The Android app

Two doors from a phone — your own server, or a private repository on GitHub — the share sheet that captures into the vault, updates, and what it deliberately does not do.

Astrolabe for Android is an APK on the releases page. It is a door onto the vault you already keep — the one your own server serves, or the one that lives in a private GitHub repository. The app has two screens of its own, a connection screen and a capture sheet, and after the first of those it hands the whole display to the reading room, full screen. Everything you know about Astrolabe on a laptop is the same here, because it is the same: the web client already lays itself out for the hand — screens, a bar of five doors, sheets, thumb-sized targets — and reads Arabic from the right, and the app ships none of that twice.

What it is

The app opens one of two doors, and you choose which on its first screen.

Your own server. The phone holds no vault, no repository and no working copy. It reads and writes through the same HTTP API the web client uses, over the same session cookie, so every question about what happens when two places edit one note has the answer the server always gives — a save that would overwrite a version you never saw is refused, not merged, exactly as it is in a browser (when the file changed under you). Backup & sync is the server's job and stays there. This is the door the app was built for and still the one to use if you run an instance; a shell's one job is to open only the address you gave it, and every other link in your notes goes to the phone's browser.

A private repository on GitHub, for a person who runs no server at all. The vault is copied into the app's own storage, read and written there, and pushed back — the section below is about that. It carries a real copy of your notes with git under it, which the first version of this app deliberately refused to do; what changed is the company that copy keeps. The refusal was about a phone clone living beside a live server writing the same vault, where a week-old copy waking up in a pocket is a merge conflict inside somebody's prose, resolved by a phone. A GitHub vault has no live server: the only other writer is your own laptop, through git, which is the arrangement everybody who keeps notes in a repository already lives with. Running the server itself on a phone is still refused, and on a fact rather than a preference — Astrolabe needs a current Node and phones do not have one.

Connecting

  1. Open the app and type your server's address — notes.example.com, or 192.168.1.24:6801. A bare name is taken to be https; an address on your own network (10.x, 192.168.x, 172.16–31.x, *.local, *.lan, localhost) is taken to be http. Typing the scheme yourself always wins.
  2. The app checks the address before it goes anywhere, so a typo is a sentence on this screen rather than a blank page.
  3. It remembers what worked. The next launch reconnects without a tap; the back gesture from your instance's first page brings you here to choose another server, and back from here leaves the app.
  4. Sign in on your instance's own login screen, once. The session persists — your server gives it a sliding life of seven days, so a writer who opens the app most days never meets the login screen again.

Your notes, your theme, your language and everything else are the instance's; the app changes nothing about them. The system bars (the status bar at the top, the gesture bar at the bottom) are kept off the page by the app itself, and the keyboard resizes the page rather than covering it.

Leaving a vault

Two ways back to the connection screen, from any vault. More → Change server or vault… (on a desktop-width screen, ⋯ → Change server or vault… in the bottom bar), which the web client shows only inside this app, takes you there directly — to type another address, pick a remembered one, or open a vault from GitHub. And the back gesture, once it has walked back through everything the vault had to go back to, lands there too. Signing out of an instance does not do it: you are signed out of that site and still looking at it, which is what signing out means; the door is the row above.

A vault from GitHub

Choose or open a vault from GitHub on the first screen. The app shows a short code; you type it into github.com/login/device in any browser — the phone's own, or the laptop you are already signed in on — and approve it there. Nothing asks you for your GitHub password, and the app keeps no secret of its own: this is GitHub's device flow, the one designed for a device that cannot safely hold one. It asks for a single permission, read and write your repositories, which is the narrowest scope that can reach a private one. You can withdraw it at any time from your GitHub account's applications page.

Then pick the repository your notes are in, and a branch. The app copies it into its own private storage — the newest commit only, not the whole history, because a vault with five years behind it is a minute of network you did not ask for — and opens the reading room on it. It is the same web client you use on a laptop: the editor, wikilinks, the graph, search, tags, properties, Orbits, Sigils, trackers, the calendar. Everything is on the device, so it opens and searches with no network at all.

What travels, and when

Opening the app pulls; coming back to it pulls again; and pulling a list in Notes down from its top pulls on the spot — the gesture every phone app uses for "refresh" is this app's sync now. Every save is one commit, named after the note. Pushing is held for half a minute, so a paragraph typed in nine saves leaves as one push — and it goes at once when you put the phone down. A small line near the bottom of the screen says what is waiting: 3 changes to send, Offline. Your changes are safe on this phone., Sending your changes…, 2 notes changed in both places. It never says you are synced while anything is waiting — and once everything is sent it steps aside, because "synced" is not news. It stands clear of the bar of five doors rather than over its last one. Tap it to send immediately.

A sync never moves you. The notes that changed are read again under you, and the folder you were in, the folders behind it and the note you were reading stay where they were; so does your place when Android brings the app back from the background. The folder's ‹ goes up to the folder above it, never to Today (back means up).

On a Galaxy Z Fold, and on a tablet. A note takes the page. Closed, the Fold's cover screen is a phone: one column, the bar of five doors. Opened, the inner screen is one column too — a note opened from the list fills the whole screen, ‹ comes back to the list — and it keeps tabs: open a second note and the first stays one tap away in a row under the note's bar, × closes one, and the tabs survive going back to the list, a reload and the app coming back. A tablet held upright is the same. A tablet on its side (1000 pixels wide and up) has two columns — the doors in a rail, your notes beside the note in a column a list's width — and Hide list at the foot of the rail lets the note take the page there too. Open or close the Fold, or turn the tablet, and the note you were reading stays open (on a foldable opened, and on a tablet).

Settings, and the tab that belongs to the phone

Open Settings → Backup & sync in a vault from GitHub and you get the phone's own panel, not a server's: the repository and branch you opened, the same line the app shows over your vault, a Sync now button that pulls and then pushes, the pairs of notes kept side by side (below), and Leave this vault — which forgets the repository and the token, sends you back to the connection screen, and deletes nothing from GitHub or from this phone.

Everything else you change in Settings is saved into the vault, in .astrolabe/settings.json, and committed like a note. That is the same file an instance keeps there, so a site name, a calendar, a daily-note folder or a template chosen on the phone is on your laptop the moment it pulls — and a setting chosen on the laptop is on the phone. What a phone cannot keep is not offered: the rows about visitors, uploaded fonts, a favicon, a hadith corpus or the clipper are greyed with the reason above them; under Your site only what the vault itself carries is drawn (the name, tagline, logo, favicon, default theme and footer), with no layout, home page, comments, webmentions or fediverse rows; and the Collections and Ask sections are not there at all.

When both sides changed one note

The phone never merges your prose. If a note changed here and on your laptop, the version from the repository keeps its name and the phone's version is set down beside it as <Note> (phone).md. Both are committed and both are pushed, so the pair is on every machine. The line at the bottom says how many pairs are standing, and it keeps saying it after the app is closed and opened again — until you have read the two and deleted the one you do not want. Nothing is ever merged, and nothing is ever thrown away.

What a GitHub vault does not do

It has no public half, so it cannot publish, and it has no blog, no visitors, no marginalia, no site designer and no clipper token. It has no data directory on a disk, so uploaded fonts and PDF annotations are not there. It has no second instance to sync with, because it is the sync. Each of those says so when you reach it, in a sentence naming what is missing and in the language you read the app in, rather than failing quietly. A note's past comes from the repository — the commits made since the copy was taken, which is where this copy's history begins.

Your notes go nowhere but your own repository. The app has no server of its own and no account with anybody.

Registering the app, if you build it yourself

Two ways in. The plain one works in every build: make a personal access token on github.com (under your profile's Developer settings, then Personal access tokens — fine-grained, with Contents: read and write on the repository that is your vault; or a classic token with the repo scope), paste it into the door, and the app checks it with GitHub before keeping it. It stays on the phone and is sent only to github.com, as the password on every git request. The other way is the Sign in with GitHub button — a code you read off the phone and type on github.com — which needs a GitHub OAuth App id baked into the build: make one under Developer settings → OAuth Apps → New OAuth App, turn Enable Device Flow on, and put its Client ID in mobile/.env as ASTROLABE_GITHUB_CLIENT_ID before building. There is no client secret; the device flow does not use one. A build without an id still has the door: the button is simply not drawn, and the token field is.

The share sheet

Share a link, a paragraph or a sentence from any app and choose Capture to Astrolabe. The sheet appends it as a timestamped bullet to today's inbox note, Inbox/YYYY-MM-DD.md, creating the note and the folder if this is the day's first capture. The write carries the note's modification time as a precondition, the same way the editor's saves do; if the note moved underneath (you were editing it on the laptop), the sheet re-reads and appends again, once. An append is the rare write where that is safe: what is being added was not in the file either time.

The sheet runs in its own task, so a capture never costs you your place in the app: share, see the confirmation, and you are back where you were.

This is the app's own sheet. The installed website — the site added to the home screen from the phone's browser, described under Capture — has a share target of its own that files a shared page under Clips/ and a shared sentence under ## Captured in today's daily note. Both roads lead into the vault; the app's is the one that works before the site is signed in anywhere, and the site's is the one that clips a page.

The installed site, and the app

You do not need the APK to have Astrolabe on a phone. The site is installable from the browser (Add to Home Screen), and the installed site opens full screen, carries the site's name and the colours of its default theme, keeps the notes you have read for offline reading, and appears in the phone's share sheet. The app adds three things over that: a connection screen that remembers your server and checks it before opening, a capture that needs no browser and no open page, and a back gesture that behaves like an app's rather than a browser's.

Inside either, a line is captured from the field at the top of Today (a vault from GitHub keeps it too: the line lands in the note you name, or in the day's inbox, and is committed like any other edit), and Sigils, Orbits, the library, the graph and the rest of the tools are rows under More.

Updates

The phone learns about a new APK the way the desktop learns about a new AppImage: one request to the releases page, once per launch, on a background thread. A sideloaded app cannot update itself — the phone's package installer is the only thing allowed to replace it — so the most the app can honestly do is say that a release exists and hand the APK to the browser, which downloads it and offers Install. The new copy is signed with the same key, so Android treats it as the update it is: notes, settings and sign-in are untouched.

Quiet by design: nothing is shown when the app is current, and a release you dismissed with Later is not mentioned again for a day. Everything on the web side reaches the phone the moment the server updates; the APK only changes when the wrapper itself does, which is rare.

What it does not do

No camera, no location, no contacts, no storage, no analytics, no push notifications. Its manifest asks for network access and — since 3.24, for voice notes — the microphone, which Android asks you about the first time you record and never before. Pointed at your own server it has no offline mode of its own: the page it shows keeps the web app's offline copy the way a browser does, and when there is no copy and no server it says so and stops. A vault from GitHub is the other case entirely — it is the copy, and it opens with no network at all.

Installing it

The APK is not on any store; install it yourself. Copy the .apk to the phone (a file-sync app, a cable) and open it in the phone's file manager. Android asks permission to install unknown apps for that file manager; grant it, install, and revoke it afterwards if you like. Installing a newer APK over an older one keeps its data, as long as both were signed with the same key — which every release is. A build you made yourself from the repository is signed with a key of its own and cannot replace a release, or be replaced by one; uninstall first.

The app permits plain http and trusts the phone's own certificate store, because a self-hosted vault at http://192.168.1.24:6801 or behind a private certificate authority is the case it exists for — and it only ever talks to the one host you named.

Edit this page on GitHub

Astrolabe is free software. These pages are built from the Markdown in the repo's docs folder.