← Tutorials

Getting Started with CUST/OS

This guide walks through installing CUST/OS in ATAK, loading a local model, and making your first tool call. The starter configuration uses Gemma 4 E2B-it for chat, Whisper for speech-to-text, and Nomic embeddings for skill selection.

Download the model files before offline use. With local providers loaded, this setup can run model requests without a cloud service or inference API key.

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)

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

Skills and models are installed separately from the APK. Get the starter skills, configuration, and model download instructions from the CUST/OS starter kit.

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 default chat provider requires the Gemma 4 E2B-it model file. To use another model, update the provider configuration to match. See models/README.md for the required files and download instructions.

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 Status to check on-device-gemma4 (chat), on-device-embed (embeddings), and on-device-whisper (transcription). Wait for the model files to load. If a provider stays offline, tap its row for the error and check the model path and available memory.

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 and uses the configured chat model to respond. With the starter local providers active, the model request runs on the device.

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.

Response time depends on the device, models, and recording length. Check transcription accuracy and the returned coordinates before relying on the voice workflow.

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

If your deployment permits remote inference, you can add a cloud provider. Its priority sets when the router tries it, and security mode and classification settings determine whether it is eligible.

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.

A provider with taskPriority: 5 is tried after one with taskPriority: 1, provided both pass the routing filters. A specialist agent can also use its own configured provider through delegation. Security modes that exclude the cloud tier block those providers regardless of whether an API key is stored.

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

Where to go next

Once the local chat and tool call work, continue with:

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.