Architecture Overview

CUST/OS is an ATAK plugin structured as a runtime -- it loads and executes operator-authored capabilities at startup, not a fixed application with a fixed feature list. This page is a 30-second tour of the major subsystems.

The big picture

                    ATAK (host process)
                    ┌────────────────────────────────────┐
                    │         CUST/OS plugin              │
                    │                                     │
                    │   UI (NavBar + panels)              │
                    │           │                         │
                    │           ▼                         │
                    │   Agent runtime (ReAct loop)        │
                    │     │       │        │              │
                    │     ▼       ▼        ▼              │
                    │   Skill   Inference  Security       │
                    │   runtime  router   (hooks, gates)  │
                    │                                     │
                    │   Memory · Voice · Automation · IPC │
                    └────────────────────────────────────┘
                                  │
                                  ▼
                    /sdcard/atak/custos/
                    ├── config/custos.yaml
                    ├── skills/...           (operator-authored)
                    ├── automations/...      (operator-authored)
                    └── models/...           (on-device weights)

The APK ships with zero skills. Everything the agent can do lives on disk, loaded at runtime, editable by the operator, hot-reloaded on save.

Lifecycle

The plugin boots in ordered phases:

Configuration -- read the operator's config file
Security -- initialize the audit log and skill verification
Memory -- open the conversation store, mark any incomplete chains from a prior crash
Inference -- connect to configured LLM, embedding, vision, and voice providers
Agent -- initialize the script sandbox
Skills -- scan the skills directory, parse metadata, start the file watcher for hot reload
Voice -- initialize push-to-talk, speech-to-text, and text-to-speech routing
IPC -- register the cross-device delegation listener
Scheduling -- start the automation scheduler
UI -- created lazily when the operator opens the panel

The first three phases are fatal -- if any fails, the plugin enters a degraded state and reports the error. The remaining phases tolerate failures and continue with reduced capability.

On-device models (running natively on the handset) start asynchronously in the background so they never block the UI.

Agent runtime

The agent uses a ReAct loop -- a published reasoning pattern where the model plans, acts, observes, and repeats:

Build context: assemble the system prompt, selected skills, and conversation history.
Call the LLM and stream tokens to the operator in real time.
If the response includes tool calls, evaluate security rules, gate on impact level, execute the tools, and append results.
Loop back to step 2 with updated context.
Stop when the model responds with text only (no tool calls) or the iteration limit is reached.

The operator can interrupt or redirect the agent mid-loop. Only one reasoning loop runs at a time. See The ReAct loop.

Inference layer

The inference router is a per-task failover system. Each task -- chat, embedding, transcription, text-to-speech, vision -- has its own list of providers sorted by priority. On every call the router walks the list, skips unhealthy or blocked providers, and tries the next one.

Providers are grouped by tier (handheld, pack, mobile, mounted, command-post, cloud). Security modes can block entire tiers -- for example, standalone mode restricts inference to the operator's own device, while EMCON mode allows the handheld and wired pack peripherals. Health checks run continuously so sick providers are skipped automatically. See Inference routing and Tiers and priority.

Script runtime

Skills are sandboxed scripts that run inside a controlled environment with:

A restricted set of device APIs the script can access
A blocklist of dangerous operations (process execution, file deletion, network sockets)
Filesystem access limited to the CUST/OS data directory
Per-execution instruction limits to prevent runaway scripts
Concurrency limits to prevent resource exhaustion

Scripts interact with the host application and ATAK through injected bindings -- functions the runtime makes available for querying the map, placing markers, accessing other plugins, scheduling automations, and more. The set of available bindings is controlled by the operator's configuration. See Skills as runtime, not bundle.

Memory

Each conversation maintains its own message history. When the conversation grows long, CUST/OS summarizes older messages to preserve important tactical information (coordinates, callsigns, decisions, tool results) while staying within the model's context window. The operator can have multiple parallel conversations for different tasks.

A separate persistent memory layer stores key-value facts (callsigns, objective locations, standing orders) that survive across conversations and are automatically included in the agent's context every turn. See Memory and context.

Voice pipeline

Push-to-talk voice interaction:

The operator long-presses the PTT button and speaks.
Audio is captured and sent to a speech-to-text provider.
The transcript is fed to the agent as a normal message.
The agent's final response is sent to a text-to-speech provider and played through the speakers.

If no speech-to-text provider is available, the PTT button is disabled and the operator uses text input. Voice providers follow the same tier and failover rules as all other providers.

Automation

Three trigger types let CUST/OS act without operator input. The trigger shape is auto-detected from the expression — there's no @type annotation to pick:

Scheduled — cron expressions or one-shot timers (0 6 * * *, in 20m)
Monitors — duration-based intervals (15s, 30m, 2h); optional ALL_CLEAR convention surfaces status in the UI
Events — ATAK broadcast actions, with filter logic implemented as a guard clause inside the Lua body

When an automation fires, its run(ctx) function executes deterministically as Lua — no LLM turn, no prompt assembly, no token spend. If reasoning is actually required, the Lua body explicitly calls tools.call("delegate", {agent_name = "...", task = "..."}), which routes through the normal agent pipeline with the named specialist. This separation is deliberate: small on-device models don't get hammered by every tick of a 15-second monitor. See The automation model.

Security

CUST/OS uses defense-in-depth with multiple independent layers:

Sandboxing -- skills run in restricted environments with controlled API access
Approval gates -- high-impact actions require operator confirmation
Pre/post hooks -- configurable rules that allow, deny, or require approval for specific tools
Immutable audit log -- every inference call, tool execution, and operator action is recorded and cannot be modified
Classification boundaries -- providers are tagged with classification levels; data doesn't flow to providers below the configured ceiling
Skill trust levels (WIP) -- skills carry a trust level (verified vs community). The signature verification path exists in code but is not yet called from the skill loader; security.requirePki is a declared intent, not enforced behavior in this release.

Every layer that is wired fails closed -- an unknown condition defaults to deny, not allow. See Trust and classification.

Cross-device delegation (WIP)

Delegation also works across devices: a specialist agent can live on a remote CUST/OS node reachable over the TAK mesh. The request is packaged as a CoT broadcast, the specialist reasons on its side, and the response comes back as a tool result. Each side stays within its own security boundary — the delegating node sends only the task description, and the specialist executes tools locally with its own approval gates and audit log.

The transport ships but hasn't been vetted end-to-end against a second live CUST/OS node yet; treat cross-device delegation as exploratory in this release. Local delegation (specialist agents running on the same device against different providers) is stable and the day-to-day path.