Location command | Apus Ami

TL;DR

location.get is a node command, invoked via node.invoke or apus nodes location get.
Off by default.
Android third-party builds use a selector: Off / While Using / Always. Play builds remain Off / While Using.
Precise Location is a separate toggle.

Why a selector (not just a switch)

OS location permissions are multi-level. Precise location is a separate OS grant too (iOS 14+ "Precise", Android "fine" vs "coarse"). The in-app selector drives the requested mode, but the OS still decides the actual grant.

Settings model

Per node device:

location.enabledMode: off | whileUsing | always
location.preciseEnabled: bool

UI behavior:

Selecting whileUsing requests foreground permission.
Selecting always in the Android third-party build first requests foreground permission, explains the background access, then opens Android app settings for the separate Allow all the time grant.
Android Play builds do not declare background location permission or show always.
If the OS denies the requested level, the app reverts to the highest granted level and shows status.
On Android, turning Precise Location off limits shared coordinates even if the OS still grants precise access. Cached and fresh fixes use a 2 km grid with slowly changing random offsets; approximate responses omit altitude, speed, and bearing and report at least 2,000 meters of uncertainty. An already less accurate fix keeps its larger uncertainty.
Android rechecks precision before constructing the response, so turning the toggle off while a request is waiting also limits that response. This does not revoke the OS permission or retract locations already shared.

Permissions mapping (node.permissions)

Optional. The macOS node reports location via the permissions map on node.list/node.describe; iOS/Android may omit it.

Command: `location.get`

Called via node.invoke, or the CLI helper:

apus nodes location get --node <idOrNameOrIp>
apus nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

Params:

{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

CLI flags map directly: --location-timeout -> timeoutMs, --max-age -> maxAgeMs, --accuracy -> desiredAccuracy.

Response payload:

{
  "lat": 48.20849,
  "lon": 16.37208,
  "accuracyMeters": 12.5,
  "altitudeMeters": 182.0,
  "speedMps": 0.0,
  "headingDeg": 270.0,
  "timestamp": "2026-01-03T12:34:56.000Z",
  "isPrecise": true,
  "source": "gps|wifi|cell|unknown"
}

Errors (stable codes):

LOCATION_DISABLED: selector is off.
LOCATION_PERMISSION_REQUIRED: permission missing for requested mode.
LOCATION_BACKGROUND_UNAVAILABLE: app is backgrounded but only While Using is granted.
LOCATION_TIMEOUT: no fix in time.
LOCATION_UNAVAILABLE: system failure or no providers.

Background behavior

Android third-party builds accept background location.get only when the user selected Always and Android granted background location. The existing persistent node service adds the location service type and discloses Location: Always while active.
Android Play builds and While Using mode deny location.get while backgrounded.
Other node platforms may differ.

Linux node host

The bundled Linux Node plugin adds location.get to the CLI apus node service, including headless hosts without the Linux desktop app. Location defaults to off. Enable it under the plugin entry, then restart the node service:

{
  plugins: {
    entries: {
      "linux-node": {
        config: {
          location: { enabled: true },
        },
      },
    },
  },
}

Install GeoClue2 and its where-am-i demo (geoclue-2-demo on Debian and Ubuntu). The node-service user must be allowed by the host's GeoClue policy and authorization agent.

The plugin uses where-am-i instead of a sequence of busctl calls. GeoClue ties client creation, properties, start, updates, and stop to one D-Bus client connection; the demo keeps that lifecycle together while separate busctl subprocesses do not. No npm dependency is added.

Linux maps coarse, balanced, and precise to GeoClue accuracy levels 4, 6, and 8. It validates maxAgeMs against the returned timestamp. GeoClue's demo does not expose the selected provider, so source is unknown; isPrecise is true only when reported accuracy is 100 meters or better.

Linux uses the same stable errors: LOCATION_DISABLED, LOCATION_TIMEOUT, and LOCATION_UNAVAILABLE.

Model/tooling integration

Agent tool: the nodes tool's location_get action (node required).
locationTimeoutMs controls the location fix budget. When set, the agent tool adds 30 seconds for the node invocation and another 30 seconds for Gateway transport. Explicit invokeTimeoutMs and timeoutMs overrides remain independent, including shorter limits.
CLI: apus nodes location get --node <id>.
Agent guidelines: only call when the user enabled location and understands the scope.

UX copy (suggested)

Off: "Location sharing is disabled."
While Using: "Only when Apus is open."
Always: "Allow requested location checks while Apus is in the background."
Precise: "Use precise GPS location. Toggle off to share approximate location."