Skip to Content
DocumentationCompanion Spatial

🚀 Companion Spatial

See your digital footprints in the real world. A phone-first augmented-reality web app that overlays nearby places, history, and weather on your camera view, guides you to a place by compass, and records the trail of where you have been.

Open it on your phone. The address is HTTPS, which the camera and sensors need. The live site and the container that the Hub installs are deployed separately, so they can differ.

Get a Companion Core, a personal AI appliance and local server, or download Companion Hub to turn a computer you already own into one.Buy Companion Core →Download Companion →Back to ci.computer
Companion Spatial AR view on a phone: a title bar with menu, compass, and settings buttons and an altitude readout, a row of Wikipedia place markers near the horizon, a targeting reticle over one marker with its name and distance below, and a heading-up minimap at the bottom
The AR view with live Wikipedia places around a simulated location in San Francisco. The camera feed is replaced by a plain backdrop.

Source and container image

The source for Companion Spatial is in a private repository, so this page doesn’t link to it. The container image and the Hub store entry are public:

  • Container registry: ghcr.io/companionintelligence/ci-webxr-time-machine:latest
  • Marketplace manifest: App ID ci-webxr-time-machine

Install & availability

Available now. Install from the Companion Hub App Store. The store lists it as Companion Spatial. Earlier versions of these docs called it Spatial Time Machine.

Hub App StoreSearch Companion Spatial → Install
Web UI port5173 inside the container, on the Hub’s own port for the app (the Hub app card shows it)
Minimum Hub version0.2.27
Architecturelinux/amd64 and linux/arm64 (multi-arch)
State & persistenceStored in your browser: your trail and imported layers in IndexedDB, your settings in local storage. The container has no volumes

The Hub store installs the latest image. As of 30 October 2026, latest is the same image as the v0.1.0 tag, built on 29 October 2026, and this page describes it. The Hub pulls this app’s image when it installs the app, not each time the app starts, so a Hub that installed Companion Spatial earlier can still be running the 6 September 2026 image.

Overview

Companion Spatial is a phone-first augmented-reality web app. Hold up your phone and it combines the camera view with the compass and motion sensors to place information about your surroundings in the scene: nearby points of interest, Wikipedia places, and overhead aircraft, with the current weather in the title bar. A headset is not required.

Places come from public open APIs, and the map uses OpenStreetMap tiles by default. Your trail stays on your device in IndexedDB, and you can export it as GPX or GeoJSON. You can also import GPX and GeoJSON files and, if you run Companion Memory, show its places and events on the map and in the AR view.

How it works

Companion Spatial is a static single-page app. The container serves the built site with nginx. The app has no backend of its own: your browser reads the sensors, calls the open data services directly, and keeps what it saves on your device.

Sensors and orientation

  • Position comes from the browser’s geolocation.
  • iOS uses the device orientation events together with the compass heading that Safari reports. The app asks for motion access on your first tap.
  • Android follows Chrome’s absolute orientation stream, which is referenced to magnetic north, for as long as it delivers readings. It falls back to the relative stream, whose heading has an arbitrary origin, when it doesn’t. The app applies no declination correction, so labels can be off by your local magnetic declination.
  • No motion access. If you deny motion access, the app follows your GPS heading when it has one.
  • No WebXR. The app never starts a WebXR session, on any device. It uses the compass and motion sensors everywhere.

Places and refresh

The app asks for places when AR starts and every 2 minutes after that. Overpass answers are cached on your device for 7 days, and the app backs off when Overpass turns requests away. Weather refreshes every 10 minutes.

Each data source is a third-party public service, and the requests carry your current coordinates. The map tiles tell whoever serves them roughly which area you are viewing. Your Hub doesn’t proxy any of them. Settings → Tile Source points the default map provider at your own tile server instead.

The Hub install form has one option, Share crash reports. It is on by default. While it is on, the app sends error reports to Companion Intelligence, with credentials, home-directory paths, and coordinates removed first. The app also sends performance traces for about one page load in ten, and a replay of the screen, with text masked and media blocked, for about one session in ten and for every session that hits an error. Turn the option off to stop all reporting.

Camera, GPS, and motion sensors require a secure context (HTTPS). Open the app through an HTTPS address, such as an exposed app hostname or your Hub over Tailscale, and AR works. Opening it over plain http://<hub-ip>:<port> shows “AR needs a secure connection” — this is browser security policy by design, not a bug.

Current capabilities

What Companion Spatial does today, in the v0.1.0 build:

  • Phone AR via camera + compass/motion sensor fusion to place markers at the real bearing and distance of each place. A reticle in the middle of the screen names the place you center, with its distance. Select it to open a card with its type, distance, and altitude
  • Compass navigation — select a place, then Navigate, and follow a heading arrow with live distance. Select the compass button in the title bar to stop
  • A spatial map and a list — a heading-up minimap that expands to a full map, and a distance-sorted list of what’s around you
  • Category filters — turn Mountains, Lakes, Cities, Buildings, Airports, Parks, History, Medical, Wikipedia, and Aircraft on or off, and set a maximum distance (20 km by default, from 1 to 80 km)
  • Live data from public APIs: nearby places (OSM Overpass ), articles (Wikipedia ), weather (Open-Meteo ), and aircraft (OpenSky )
  • Your trail — recorded as breadcrumbs on your device in IndexedDB, drawn in the AR view, and exportable as GPX or GeoJSON (Settings → Data)
  • Imported layers — bring in a GPX or GeoJSON file from the categories drawer; its points appear as places on the map and in the AR view, and you can rename, hide, or delete each layer. The file stays on your device
  • Companion Memory, optional and read-only — connect your own server in Settings → Companion Memory to see its places and events pinned where they happened. The app never writes back
  • Install to your home screen — it is a progressive web app, so your browser can install it and open it as a standalone app. Live data still needs a connection
  • iOS motion permission prompt on first tap

Everything the overlay shows comes from your phone’s sensors, public APIs, and, if you connect one, your Companion Memory. The app stores your trail, your imported layers, your settings, and cached place data on your device only. If you connect Companion Memory, your server address and API key stay there too.

Companion Spatial AR view with a place card at the bottom showing the place name, a Wiki label, distance, altitude, and a Navigate button
Select the place under the reticle to open its card. Navigate starts the heading arrow.

Desktop browsers show the interface, but without a camera and motion sensors the overlays have no view direction to follow.

The OpenSky aircraft feed may be blocked by CORS depending on the network and the API’s current policy. When that happens, the app shows Aircraft feed unavailable once and stops asking for an hour (five minutes after an HTTP error), so aircraft overlays don’t appear. This is an upstream/API limitation, not a fault in your Hub.

Spatial Map dialog with Map and List toggle buttons, a dark OpenStreetMap map of a city waterfront with a light marker for your position and book icons for Wikipedia places
The Spatial Map, opened from the minimap. List shows the same places sorted by distance.

Select ☰ in the title bar to open the categories drawer, where you filter what appears:

Categories drawer with Personal toggles for History and Memories, map layer toggles for Mountains, Lakes, Cities, Buildings, Airports, Parks, History, Medical, Wikipedia, and Aircraft, and a Max Distance slider set to 20 km
The categories drawer.

Scroll the drawer to its end to find Imported, where you add your own GPX or GeoJSON layers:

The lower part of the categories drawer: a Max Distance slider set to 20 km, an Imported section with an Import GPX / GeoJSON button and the line No imported layers yet, and an About section with Companion Intelligence links
The Imported section of the categories drawer.

Use cases

  • Hold up your phone outdoors and see nearby landmarks, Wikipedia places, and the weather overlaid on the scene
  • Check the name and distance of the mountain, lake, or building you are looking at
  • Spot aircraft passing overhead (network permitting)
  • Build a local, private log of the places you’ve explored and export it as GPX or GeoJSON
  • Bring in the waypoints from a GPX or GeoJSON file and see them in AR
  • See your Companion Memory’s places and events where they happened

Supported platforms

PlatformModeNotes
iOS / Android phoneAR (camera + sensors)Requires HTTPS; iOS prompts for motion permission
Desktop browserUI onlyRenders the interface; no view direction to follow. Without a camera, the app says so
WebXR headsetNot supportedThe app never starts a WebXR session

Setup

Install from Hub

Search for Companion Spatial in the Hub app store and install.

Open over HTTPS

On your phone, open an HTTPS address for the app: an exposed app hostname, or your Hub over Tailscale. A secure context is required for camera, GPS, and motion access. See Finding your app’s URL if the app card doesn’t show one.

Grant permissions

The first screen is dark with a spinner and Tap anywhere to start. Tap to start AR. On iOS you’ll be prompted to allow motion access on first tap. Allow camera and location when asked.

Usage

Starting AR

Open the app over HTTPS on your phone and tap to begin. Point your phone at your surroundings; overlays anchor to real-world directions using the compass and motion sensors. The title bar shows your altitude and, once it loads, the current weather.

Exporting your history

Your explored locations are saved locally in IndexedDB. Open Settings and, under Data, select Export GPX or Export GeoJSON to download your history. The GPX file holds your trail and the places currently loaded as waypoints. The GeoJSON file holds your trail as a line and each place as a point. Use either in mapping tools. Clear History erases your trail.

Importing a GPX or GeoJSON file

Open the categories drawer, scroll to Imported, and choose Import GPX / GeoJSON, or drop a file anywhere in that section. The app parses the file on your device and never uploads it. Only points are drawn: lines and polygons in a file, such as a GPX track or route, are stored but don’t appear. Use each layer’s controls to rename, hide, or delete it.

Connecting Companion Memory

Open Settings → Companion Memory and enter your server’s address. Then paste an API key and choose Test Connection, or sign in with your username and password. Use Memories from to limit how far back the app asks, and the Memories toggle in the categories drawer to show or hide them.

Your Companion Memory server must allow this app’s origin. Its operator adds the origin, port included, to CORS_ALLOWED_ORIGINS. Create the API key under Settings → API Keys in Companion Memory with the Read-only capability and no scope boxes ticked, because GraphQL refuses a scope-limited key. If you sign in with your account instead, the app has full access as you for five minutes at a time. It renews the session while the page is open, using your password held in memory only, and forgets it when you reload.

Troubleshooting

“AR needs a secure connection” You opened the app over plain HTTP. Camera, GPS, and motion require HTTPS — use an HTTPS address for the app, as described in Open over HTTPS.

“Camera or location access was denied” or “No camera was found on this device” Allow camera and location for the site in your browser’s settings, then reload the page. The AR view needs a camera, so open the app on a phone. Try again on the start screen re-runs the start.

Desktop won’t track a view direction Desktop browsers show the interface but have no camera or motion sensors to follow. Use a phone.

iOS isn’t tracking motion iOS requires an explicit motion-permission grant on first tap. If you denied it, choose Enable motion sensors to ask again.

The labels are turned from where the places are on Android On Android, the app follows Chrome’s absolute orientation stream, which is referenced to magnetic north, so labels can be off by your local magnetic declination. When your browser can’t give an absolute reading, for example because the phone has no magnetometer or motion sensors are blocked, the app says Compass unavailable, so labels may be turned after about 3 seconds, once per session. Use Settings → Compass Calibration → Manual Heading Offset to line the labels up. Settings → Sensor Diagnostics shows which orientation source the app is using.

No aircraft overlays The OpenSky feed may be CORS-blocked on your network or by the API. Other data sources are unaffected.

Few or no places appear The app needs internet access to Overpass and Wikipedia. Overpass can answer slowly or turn requests away when it is busy, so wait a minute and check again. The app asks again every 2 minutes.

Last updated on