← Tutorials

Getting Started with CUST/OS

CUST/OS is the Guardian of the Tactical Edge — an agentic AI runtime that lives inside ATAK and runs on the device the operator is fighting from. By the end of this guide you will have CUST/OS installed and talking to a local on-device model, with no cloud connection required, no API keys, and no network in the loop.

CUST/OS is edge-first. The default deployment runs Gemma 4 E2B-it locally on the device for reasoning, Whisper locally for speech-to-text, and Nomic embed locally for skill selection. Cloud providers are an optional layer you can add later for back-line analysis — not something the runtime depends on.

What you need

  • An Android device running a supported version of ATAK-CIV
  • About 10 GB free on the device (for the on-device model weights)
  • A workstation with adb available if you want to use the scripted installer (optional — the minimum path is device-only)

That's it. You do not need an API key. You do not need a cloud subscription. You do not need a workstation for the core flow.

Step 1 — Install the plugin

The CUST/OS plugin installs from the Google Play Store like any other ATAK plugin. On the device:

  1. Open the Play Store and search for CUST/OS.
  2. Install it.
  3. Open ATAK-CIV. The plugin manager will detect CUST/OS and offer to load it — accept.

If your unit or integrator distributes via sideload, MDM, or the ATAK plugin manager's direct-install path instead:

adb install custos-plugin.apk

Either way the plugin ends up registered with ATAK and available on next launch.

Step 2 — Install the skill kit and on-device models

CUST/OS ships zero skills inside the APK on purpose — the runtime is one thing, the capabilities and model weights are another. The default skill kit, starter configuration, and model download instructions live in the open-source github.com/nimbusxr/custos repo.

From a workstation:

git clone https://github.com/nimbusxr/custos.git
cd custos

# Download the on-device model weights into models/
# (Gemma 4 E2B-it, Nomic embed, Whisper tiny — see models/README.md for links)

./install.sh

install.sh pushes the starter custos.yaml, the default skills, the scratch tests, and every weight file you dropped into models/ to the right paths under /sdcard/atak/custos/ on the device. The plugin hot-reloads — no ATAK restart needed.

The only mandatory weight is Gemma 4 E2B-it if you want on-device chat. Without it, CUST/OS has no chat provider by default and won't be able to reason. See models/README.md in the kit repo for every file, why it's needed, and where to download it.

If you can't run a workstation install, your integrator can push the same content via MDM — the on-device layout is just files under /sdcard/atak/custos/.

Step 3 — Open ATAK

  1. Launch ATAK-CIV on the device.
  2. Skip past any setup prompts.
  3. Look for the CUST/OS toolbar icon on the map. Tap it.
  4. The CUST/OS panel slides in.

You should see the NavBar on the left edge with icons for Chat, Automation, Status, Editor, Audit, Security Mode, and Settings. At the bottom of the NavBar is a large round PTT button.

Tap the Status icon to verify the on-device providers are online: on-device-gemma4 (chat), on-device-embed (embeddings), and on-device-whisper (transcription) should all show green within 20 seconds of ATAK starting. If any show offline, tap the row for the error — almost always a missing weight file in /sdcard/atak/custos/models/.

Step 4 — Send your first text message

  1. Tap the Chat icon in the NavBar.

  2. Tap the text field at the bottom and type:

    Where am I?

  3. Tap the send icon.

The agent reads your position from ATAK's self-marker, reasons about it on-device with Gemma 4, and streams a response back to the chat panel. No network traffic is generated for this turn — everything runs locally.

Step 5 — Talk to the agent

  1. Long-press the PTT button at the bottom of the NavBar.
  2. The chat panel switches into recording mode and shows a live waveform.
  3. Say something like "Place a marker called bravo at my position."
  4. Release the button.

What happens next:

  1. Your voice is transcribed by on-device Whisper (no network).
  2. The transcript is reasoned over by on-device Gemma 4 (no network).
  3. The agent places a marker named "bravo" on the ATAK map.
  4. The response is spoken back through text-to-speech.

Total round-trip, end-to-end, on a modern handheld: about two seconds. No cellular, no Wi-Fi, no TAK server required.

If the marker doesn't appear, open the Audit panel from the NavBar to see what tool calls actually fired.

Step 6 — Stop the agent mid-task

If the agent is taking too long:

  1. While it is reasoning, tap the stop icon in the chat input area.
  2. The current task is interrupted and any pending tool calls are abandoned.
  3. The chat shows a partial response.

Step 7 — (Optional) Layer in a cloud provider

CUST/OS doesn't need a cloud provider to work — the default configuration runs entirely on-device. But for tasks where a bigger model is worth the round-trip (deeper analysis, longer context, complex reasoning), you can add one as a fallback that only runs when you explicitly ask or when the mission's security mode allows it.

The shipped custos.yaml has several cloud providers available as commented-out examples (Anthropic Claude, OpenAI GPT, xAI Grok). Pick one:

  1. Open the Editor panel in the NavBar.
  2. Open /sdcard/atak/custos/config/custos.yaml.
  3. Uncomment the provider block you want and save.
  4. Open the Status panel, tap the new provider's row (it'll show as offline), and tap Set Key in the provider dialog. Paste your key. The key is stored in the encrypted Android Keystore; it never goes into custos.yaml.

Cloud providers get taskPriority: 5 or higher in the default config — lower than the on-device Gemma 4's taskPriority: 1 — so they only run if the on-device model is unavailable or if you explicitly route a task to them via delegation. Under EMCON, Standalone, or any other security mode that excludes the cloud tier, they're filtered out entirely regardless of API key state.

See How-to: Add a cloud provider for the full provider catalog.

Where to go next

You have a working install running entirely on-device. The natural next steps are:

Cleanup

To remove CUST/OS from a device:

  • Uninstall the plugin from the Play Store (or via adb uninstall com.nimbusxr.custos.plugin.civ).
  • Optionally wipe the installed content: adb shell rm -rf /sdcard/atak/custos.

Conversation memory and the audit log are wiped when you uninstall the plugin. The content under /sdcard/atak/custos/ (skills, scratches, models, config) persists until you remove it explicitly.