Installation

Install the starter kit

Add the MIT-licensed collection of 44 skills and 101 tools to your Android device. This guide covers the required apps, starter files, and model downloads. Install through a supported browser or use the terminal instructions.

  1. 01

    Before you start

    Install the required apps. For installation from a computer, enable USB debugging and connect your phone.

    1. 1.1Install ATAK-CIV

      CUST/OS runs inside ATAK. Install the civilian build (ATAK-CIV) from the Play Store first. If you already have ATAK, skip this step.

      Get ATAK on Google Play
    2. 1.2Install the CUST/OS plugin

      Install the plugin from the Play Store before adding the starter kit. Open ATAK and enable CUST/OS when prompted.

      Get CUST/OS on Google Play
    3. 1.3Enable USB debugging

      Settings → About phone → tap Build number 7 times → back → Developer options → USB debugging. Menu names vary by phone manufacturer.

    4. 1.4Plug the phone in with a data cable

      Use a cable that supports data transfer. A charge-only cable will power the phone but will not connect it to the installer.

  2. 02

    Install the starter kit

    Copy skills, configuration, and scratch scripts to /sdcard/atak/custos/. The options below depend on your browser.

  3. 03

    Model weights

    The starter custos.yaml enables on-device providers whose model files must be downloaded separately. Some downloads require accepting the model's license. Download each file, then drop it in below.

    Filenames matter. The paths in custos.yaml reference each model by name. If you change a filename, edit the matching url: line in the config.

    Skipping a model is fine — just the matching provider will show offline in the Status panel. You can add it later without re-doing anything else.

    Full instructions, including how to swap in different weights or pair .jinja chat templates with llama.cpp, live in the repo's models/README.md.

  4. 04

    Check your setup

    Open CUST/OS and check that the models are available. The default agent callsign is Custos; you can change it in custos.yaml.

    First run

    Check the plugin, voice input, and provider status.

    1. OPENOpen ATAK, tap the CUST/OS tile

      You'll find it in the ATAK NavBar. Wait for the configured local models to load. Startup time depends on the model files and device.

    2. VOICEHold PTT and talk to Custos

      Hold the PTT button while speaking, then release it. With a speech-to-text provider configured, try:

      "Custos, what skills do you have?"
      "Drop a hostile marker at my location, callsign Tango-1."
      "Zoom to 38.8951, -77.0364."
    3. STATUSOpen the Status panel

      Providers with valid configuration and model files should show ONLINE after loading. If a provider stays offline, tap its row for the error. Check for a missing model file or a filename mismatch with custos.yaml.

    Ready to try a tool call?

    Getting started →Full docs →

If something goes wrong

Troubleshooting

If USB installation fails, start with the connection and authorization checks below.

"The device is already in used by another program"▾

Another program on your computer has already claimed the USB connection to your phone. On macOS and Linux, only one program can hold a USB interface at a time — so if Android Studio, IntelliJ, a CLI adb, scrcpy, or a previous browser tab grabbed it first, the installer can't.

Fix:

  1. Fully quit Android Studio / IntelliJ with Cmd+Q (closing the window isn't enough — they keep running).
  2. If you have adb installed on the command line, run adb kill-server to stop any leftover daemon.
  3. Close any other browser tab that may have opened this install page.
  4. Unplug and replug your phone.
  5. Retry.

If IntelliJ IDEA Ultimate or Android Studio has claimed the USB connection, use the terminal installation instructions. That method shares the adb daemon with those tools.

My phone doesn't appear in the permission dialog▾

The browser pops up a device picker, but your phone isn't listed. A few things to check:

  • USB debugging is on. Settings → About phone → tap Build number 7 times → back → Developer options → USB debugging. Toggle it off and back on if it's already on.
  • Data-capable cable. Many USB-C cables are charge-only and silently fail for adb. Try the cable that came with the phone or a known-good data cable.
  • USB mode isn't "Charging only". When you plug the phone in, pull down the notification shade — if it says "Charging this device via USB" only, tap it and switch to "File transfer" or "PTP". (The mode label varies by OEM.)
  • Try another USB port, especially if you're going through a hub. Plug directly into your computer.
My phone shows up, but the "Allow USB debugging" prompt never appears▾

The phone may have remembered a previous "Deny" answer, or the prompt fired while the screen was off and you missed it.

Fix: Unlock the phone and keep it awake. Go to Settings → Developer options → Revoke USB debugging authorizations and tap it. Unplug and replug. Retry — the prompt will fire again, and this time, tap Allow (and consider ticking "Always allow from this computer" if you plan to reinstall).

Install fails mid-way / connection drops▾

Usually a wiggled cable, an auto-locking phone, or a laptop going to sleep.

Fix: keep the phone awake while installing (Settings → Display → Sleep → longest option, or enable "Stay awake while charging" in Developer options). Use a short, sturdy USB cable. Don't touch the cable during installation. Click Install again to retry.

It says it succeeded but CUST/OS doesn't see the skills▾

The plugin hot-reloads the skills directory on each app focus or on skill change, but if you had CUST/OS open during install, force-close and reopen the plugin from ATAK to pick up the new files. You can verify the files landed with:

adb shell ls /sdcard/atak/custos/skills/

You should see ~44 custos.* directories. If the list is empty or incomplete, retry the installation.

Still stuck? Open an issue on GitHub or ask in Discussions. Include the exact error text and your browser + OS.

Prefer to do it yourself? Clone the starter kit and read the getting-started tutorial for instructions on copying the files manually.