🔭 Earth
Explore the planet in 3D. A locally-hosted, interactive 3D globe you can search, fly across, and drop personal location pins onto.
Open-source repositories
Companion Earth and its 4D temporal successor Companion Atlas are open source under the PolyForm Noncommercial 1.0.0 license:
- Successor repository (Companion Atlas):
github.com/companionintelligence/CI-Spatial-Atlas - Spatial platform core:
github.com/companionintelligence/CI-Spatial - Container registry:
ghcr.io/companionintelligence/ci-earth:latest - Marketplace manifest: App ID
ci-earth
Companion Earth is deprecated. Its development moved to Companion Atlas, a 4D globe that renders your located Companion Memory events and lets you scrub through time. The Earth app remains in the Hub App Store and functions as described below for static location pinning and 3D globe navigation, while Companion Atlas is in pre-release and not in the Hub App Store yet.
Install & availability
Available now. Install from the Companion Hub App Store. Verified on the test fleet: the published image pulls, starts, serves its web UI, and survives a container restart.
| Hub App Store | Search Companion Earth (app id ci-earth) → Install |
| Port | 18813 in the store listing. The container listens on 5173. |
| Requires | Companion Hub v0.2.27 or later |
| Architecture | linux/amd64 and linux/arm64 (multi-arch) |
Overview
Companion Earth is a locally-hosted, interactive 3D globe rendered in your browser. It is built on Three.js with react-three-fiber and @react-three/xr , and renders Google’s Photorealistic 3D Tiles when an API key is supplied at build time. You search for a place, fly to it, and can save a personal “pin” for any location you visit.
Earth runs from the container served on your Hub and needs no account. Your browser makes outside requests for place searches (to OpenStreetMap’s Nominatim geocoder), for Google’s tiles when you build the image with a key, for located photos from your Companion Memory (see Current capabilities), and for font data that draws text in the 3D scene (from the jsDelivr content network, cdn.jsdelivr.net). Pins you save are stored in your browser’s localStorage on the device you used.
Architecture and subsystems
Companion Earth bridges browser WebGL/WebXR graphics with geospatial data and your personal memory graph:
flowchart TD
subgraph BROWSER["Client Browser Runtime"]
CANVAS["Three.js WebGL / WebGPU Canvas"]
R3F["React Three Fiber (@react-three/fiber)"]
XR["WebXR Headset Engine (@react-three/xr)"]
SUN["Solar Ephemeris Calculator<br/>(Time-of-day slider)"]
CANVAS --- R3F
R3F --- XR
R3F --- SUN
end
subgraph GEO["Geospatial Data Sources"]
TILES["Google Photorealistic 3D Tiles<br/>(via OGC 3D Tiles loader)"]
GEOCODE["Nominatim / Mapbox Geocoding<br/>Search query → [lat, lon, alt]"]
end
subgraph MEMORY["Companion Memory Integration"]
GQL["GraphQL Query Client<br/>/graphql query locatedMedia()"]
LOCAL[("Browser LocalStorage<br/>Personal pin collections")]
end
GEOCODE -->|"fly-to camera spline"| R3F
TILES -->|"3D geometry streaming"| CANVAS
GQL -->|"50 recent photo pins"| R3F
LOCAL <-->|"save / load pins"| R3FEvolution to Companion Atlas
While Companion Earth provides 3D globe visualization and local pin markers, Companion Atlas (CI-Spatial-Atlas) replaces its core engine:
- CesiumJS and 3D Gaussian splats: Upgrades from a procedural sphere to a dual-engine CesiumJS/Resium web globe and Three.js/R3F XR viewer (with splat reconstruction and
atlas-apibackend services currently scaffolded inCI-Spatial-Atlas). - Authenticated Companion Memory sync: Replaces Earth’s unauthenticated 50-photo startup query with authenticated GraphQL pagination against Companion Memory (
CI-Server). - Story specification: Implements
companion.atlas/story@1, enabling structured spatial narratives that link places, people, and time.
Current capabilities
What Earth does today, as shipped:
- 3D globe rendering with Three.js / react-three-fiber, optionally using Google Photorealistic 3D Tiles
- Geocoding search → fly-to navigation: type a place name and the camera animates to it. Your search text goes to OpenStreetMap’s Nominatim service, or to Mapbox if the image was built with a Mapbox key.
- “Pin this location” to save the spot you’re viewing; pins persist in browser
localStorageonly. A Collections panel lists your pins and lets you fly to one or remove it. - Located photos from Companion Memory. When the app loads, it asks a Companion Memory GraphQL address for your 50 most recent located media events and shows the images as photo pins next to your own. The request is read-only and attaches no sign-in. The address is set when the image is built (
VITE_CI_SERVER_GRAPHQL_URL), and the Hub App Store image uses the default,http://ci-server.localhost:8000/graphql. If nothing answers at that address from your browser, or your Memory requires sign-in, the request fails quietly and you see only your own pins. - Time-of-day sun-lighting slider that changes the angle of the sunlight on the globe
- WebXR scaffolding via
@react-three/xrfor headset viewing
Earth’s Companion Memory support is limited to the located photos described above. It does not import location history or show notes or conversations. The features below are on the roadmap, not in the shipped image.
Planned / roadmap
These features are described in the product vision but are not present in the current release. Treat them as future work:
- Offline tile cache / local tile server for fully offline maps
- Memory pins generated from your notes and conversations (only located photos are fetched today)
- Location-history import (Google Timeline, iOS Significant Locations)
- Companion Scan Place and scan overlays on the globe
- Rich memory cards, cluster view, and trip export / sharing
- A Settings panel for Offline Maps and Data Sources
Use cases
- Search any place on Earth and fly to a photorealistic 3D view of it
- Bookmark locations you care about as local pins on your own device
- Adjust the sun angle to see a location under different lighting
- View the globe in a WebXR-capable headset
Architecture
Everything runs in the browser from the container on your Hub. Outside requests go to Nominatim for place searches, to Google’s tile service if you built the image with a key, to the Companion Memory address for located photos, and to jsDelivr for font data:
flowchart TB
E["Companion Earth (WebGL)"]
E --> R["3D globe renderer<br/>Three.js + react-three-fiber"]
E --> G["Google Photorealistic 3D Tiles<br/>only if VITE_GOOGLE_MAPS_API_KEY was baked at build"]
E --> S["Geocoding search → camera fly-to"]
E --> L["Sun-lighting (time-of-day) slider"]
E --> P["Pin store<br/>browser localStorage, this device only"]
E --> N["OpenStreetMap Nominatim<br/>place-search text"]
E --> J["jsDelivr<br/>font data for scene text"]
E --> M["Companion Memory GraphQL<br/>located photos, read-only, no sign-in"]
E --> X["WebXR session<br/>@react-three/xr"]Technical architecture details
Companion Earth (CI-Earth-2) is a pure client-side React and Vite application served on container port 5173 (mapped to 18813 in the Hub App Store):
- Scene graph and XR runtime: Renders the globe in WebGL using Three.js,
@react-three/fiber, and@react-three/xr. WhenVITE_GOOGLE_MAPS_API_KEYis absent at build time, the renderer falls back to a procedural sphere with directional sun lighting controlled by the time-of-day slider. - Build-time environment configuration: Because Vite bundles configuration statically at build time, optional integrations are controlled by build arguments:
VITE_GOOGLE_MAPS_API_KEY: Enables streaming of Google Photorealistic 3D Tiles.VITE_MAPBOX_ACCESS_TOKEN: Switches place-search geocoding from OpenStreetMap’s public Nominatim endpoint to Mapbox.VITE_CI_SERVER_GRAPHQL_URL: Sets the Companion Memory GraphQL endpoint (defaulthttp://ci-server.localhost:8000/graphql) queried on startup for the 50 most recent located photo events (locatedPhotos).
- Client-only state: Pins created with Pin this location are serialized directly into the browser’s
localStorageunder the current origin. The container has no backend database or server-side state. - Successor architecture: Active development has moved to Companion Atlas (
CI-Spatial-Atlas), which replaces Earth’s single-renderer prototype with a dual-engine CesiumJS + Three.js/R3F viewer, authenticated Companion Memory pagination, and portablecompanion.atlas/story@1journeys.
Photorealistic 3D Tiles
Earth can render Google’s Photorealistic 3D Tiles . This requires a Google Maps API key, which must be provided as VITE_GOOGLE_MAPS_API_KEY at build time — Vite bakes the value into the static bundle. The published image is built without a key, so to enable photorealistic tiles you must rebuild the image with your key:
docker build \
--build-arg VITE_GOOGLE_MAPS_API_KEY=your_key_here \
-t ci-earth:custom .Without a key, the globe still renders, but Google’s photorealistic tiles are unavailable.
Setup
Install from Hub
Search for Companion Earth in the Hub App Store and install.
Open Earth
Use the address on the app’s card in the Hub dashboard. To see how Hub builds app addresses, see Finding your app’s URL.
Open Earth from its card on the Hub dashboard. The initial screen is the globe on a star field, with Search and Collections buttons at the top, a time-of-day slider at the bottom left, an Enter VR button at the bottom right, and the camera position along the bottom.

(Optional) Enable photorealistic tiles
Rebuild the image with VITE_GOOGLE_MAPS_API_KEY set, as shown above, then install your custom build.
Usage
Navigating the globe
Navigation is search-driven: choose Search, type a place name (city, landmark, address), and Earth geocodes it and flies the camera to the result you pick. There are no free click-drag / scroll camera controls in this build.

Pinning a location
Fly to a location you want to remember, then click Pin this location. The pin is saved to your browser’s localStorage on the current device. Pins do not sync between devices or to your Hub. Open Collections to list your pins, fly to one, or remove it.

The sun-lighting slider
The time-of-day slider adjusts the angle of the sunlight illuminating the globe — it is a lighting control, not a memory time scrubber.
Troubleshooting
Globe renders but isn’t photorealistic
The image was built without a Google Maps API key. Rebuild with VITE_GOOGLE_MAPS_API_KEY set to enable Photorealistic 3D Tiles.
My pins disappeared
Pins are stored in the browser’s localStorage. Clearing site data, switching browsers, or using a different device will not show pins saved elsewhere.
Looking for my photos / Companion Memory on the map
Earth requests located photos from http://ci-server.localhost:8000/graphql without signing in. If that address doesn’t answer from your browser, or your Memory requires sign-in, no photos appear. Notes, conversations, and location-history import are not part of this release — see Planned / roadmap.