# ATAK and iTAK usage
KestrelOS can act as a **TAK Server**: ATAK (Android) and iTAK (iOS) devices connect to it the same way they connect to any TAK Server. No plugins are required. Once connected, devices relay Cursor on Target (CoT) to each other so team members see each other on the ATAK/iTAK map, and their positions appear on the KestrelOS web map.
---
## Overview
- **ATAK** — Android Team Awareness Kit.
- **iTAK** — iOS version; uses the same TAK Server connection flow.
- **KestrelOS** — Web app and API use **port 3000**. CoT (TAK) uses **port 8089** (TLS when `.dev-certs/` or `COT_SSL_*` are set, else plain TCP). In ATAK/iTAK you connect to host and port **8089**; enable SSL if the server uses TLS.
You add KestrelOS as a **Server** connection in ATAK or iTAK (host + port **8089**). If authentication is enabled, you use your **KestrelOS username** and a **password** (local users: login password; OIDC users: ATAK password set in the web app).
---
## ATAK (Android)
### 1. Add the server
1. Open **ATAK**.
2. Go to **Settings** (or **Configuration**) → **Network** → **Connections** (or **Server Connections**).
3. Add a new connection:
- **Type:** TAK Server / Server.
- **Host:** Your KestrelOS hostname or IP (e.g. `kestrelos.example.com` or `192.168.1.10`).
- **Port:** **8089** (CoT port). Use SSL if the server runs with TLS (e.g. `.dev-certs/` or production cert).
4. If your KestrelOS instance requires authentication:
- Enable **Use Authentication** (or equivalent).
- **Username:** Your KestrelOS identifier (email or username).
- **Password:**
- **Local account:** Your KestrelOS login password.
- **OIDC account:** The **ATAK password** you set under **Account** in the KestrelOS web app (you must set it once before connecting).
5. Save and connect.
### 2. Verify
- After connecting, your device and other connected ATAK/iTAK devices should appear on the ATAK map.
- In KestrelOS, open the **Map** in a browser; you should see amber markers for connected TAK devices. They disappear after about 90 seconds without updates.
---
## iTAK (iOS)
### 1. Add the server
**Option A — Scan QR code (easiest)**
In KestrelOS, open **Settings** and find the **TAK Server (ATAK / iTAK)** section. Scan the QR code with iTAK (Add Connection → Scan QR). iTAK will add the server; you’ll be prompted for your KestrelOS username and password. If the server uses a self-signed certificate, import the trust store first (see [Self-signed certificate: import the trust store](#2-self-signed-certificate-import-the-trust-store-required-for-ssl)).
**Option B — Manual**
1. Open **iTAK**.
2. Go to **Settings** → **Network** / **Connections** (wording may vary by version).
3. Add a **TAK Server** (or **Server**) connection:
- **Host:** KestrelOS hostname or IP.
- **Port:** **8089** (CoT port). Use SSL when the server uses TLS.
4. If authentication is required:
- Turn on **Use Authentication**.
- **Username:** Your KestrelOS identifier.
- **Password:** KestrelOS login password (local) or ATAK password (OIDC; set in KestrelOS **Account**).
5. Save and connect.
### 2. Self-signed certificate (required for SSL)
If KestrelOS uses a **self-signed certificate** (e.g. `.dev-certs/`), the client must trust it or the TLS handshake never completes. You’ll see “Error authenticating with the server” and **no `[cot]` logs** on the server.
**iTAK (iOS) — Upload server package (recommended):**
Many iTAK builds only offer “Connect with credentials”, “Upload server package”, and “Scan QR”; there is no “Import Trust Store” or “Enroll with Preconfigured Trust”. Use the server package:
1. In **KestrelOS**, open **Settings** → **TAK Server (ATAK / iTAK)** and click **Download server package (zip)**.
2. Transfer the zip to your iPhone (e.g. AirDrop, email, or open KestrelOS in Safari on the phone, log in, and download there).
3. In **iTAK**: **Settings** → **Network** → **Servers** → **+** → **Upload server package** → select the zip.
4. When prompted, enter your KestrelOS **username** and **password**. The package includes the server cert so iTAK can complete the TLS handshake.
**iTAK — Plain TCP (no SSL):**
If the server package does not work, run CoT without TLS: stop KestrelOS, rename or remove the `.dev-certs` folder, then restart. The CoT server will listen on 8089 with plain TCP. In **Settings** → TAK Server, the QR will show `tcp`. Scan it or add the server manually with **SSL disabled**. You won’t get a cert prompt and the connection should reach the server.
**ATAK (Android):** If your build has **Enroll with Preconfigured Trust** and **Import Trust Store**, you can download the trust store from **https://your-server/api/cot/truststore** (when logged in), import the `.p12`, password `kestrelos`, then connect. Otherwise use the **server package** from Settings the same way as iTAK, or use plain TCP as above.
### 3. Verify
- Other TAK clients (ATAK and iTAK) that are connected to the same KestrelOS instance appear on your iTAK map.
- KestrelOS web map shows all connected TAK devices as amber markers (position only; no video).
---
## OIDC users: set ATAK password first
If you sign in to KestrelOS with **OIDC** (SSO), you do not have a KestrelOS login password. To use “Use Authentication” in ATAK/iTAK:
1. Sign in to the **KestrelOS web app** with OIDC.
2. Open **Account** (sidebar).
3. Under **ATAK / device password**, set and confirm a password, then save.
4. In ATAK or iTAK, use your **KestrelOS username** (identifier) and this **ATAK password**.
If you haven’t set an ATAK password, the TAK Server will reject your connection.
---
## Server configuration (optional)
| Environment variable | Default | Description |
|----------------------|---------|-------------|
| `PORT` | `3000` | Port for the web app and API. |
| `COT_PORT` | `8089` | Port for the CoT (TAK) server. |
| `COT_TTL_MS` | `90000` | How long (ms) a device stays on the map without updates (~90 s). |
| `COT_REQUIRE_AUTH` | `true` | Require username/password before relaying. |
| `COT_SSL_CERT` | — | Path to TLS cert for CoT (optional; default: `.dev-certs/cert.pem`). |
| `COT_SSL_KEY` | — | Path to TLS key (optional; default: `.dev-certs/key.pem`). |
When `.dev-certs/` exists (e.g. `./scripts/gen-dev-cert.sh`), the CoT server uses TLS on port 8089. For **Docker**, expose ports 3000 and 8089:
```bash
docker run -p 3000:3000 -p 8089:8089 kestrelos:latest
```
For **Helm**, expose ports 3000 and 8089 in the service or ingress.
---
## Testing the CoT endpoint
The web app is on **port 3000**, CoT on **port 8089**. From the same device (or any host with network access), you can confirm both work.
**Health (API):** `curl -k https://localhost:3000/health` (or `http://localhost:3000/health` if no TLS).
**CoT on port 8089:** If the server uses TLS (e.g. `.dev-certs/`), connect with TLS to port 8089 and send a CoT auth message:
```bash
echo '' | \
openssl s_client -connect localhost:8089 -quiet 2>/dev/null
```
If the server runs without TLS (plain TCP), use:
```bash
echo '' | \
nc localhost 8089
```
Replace `localhost` with your server host if testing remotely. **What to expect:** Server logs show `[cot] client connected`, `[cot] frame parsed as traditional`, `[cot] auth attempt username= itak`, and either `auth result valid= true` or `password match= false`.
---
## Troubleshooting
### "Error authenticating with the server" and no `[cot]` logs on the server
If iTAK shows this message but you see **no** `[cot]` lines in the server log, the connection is almost certainly **not reaching** the CoT process.
**With SSL (TLS) and a self-signed cert:** The server only runs your connection handler **after** the TLS handshake completes. If the client does not trust the server’s certificate (e.g. self-signed and not imported), the handshake fails on the client side and never completes, so the server never logs “client connected”. **Fix:** Use **Upload server package** (download from KestrelOS Settings) or import the trust store in iTAK (see [Self-signed certificate](#2-self-signed-certificate-required-for-ssl) above). No server logs until the client trusts the cert and the handshake succeeds.
1. **Confirm CoT is listening**
- When the app starts you must see: `[cot] CoT server listening on 0.0.0.0:8089 (TLS)` or `(plain TCP)`.
- If you don’t see that, the CoT server didn’t start (e.g. port 8089 in use, or you’re viewing logs for a different process).
2. **Port and host**
- In iTAK the **port must be 8089** (not 3000). Host = your server IP (e.g. 192.168.2.214).
3. **Reachability from the device**
- From the same network as your phone, run: `nc -zv 192.168.2.214 8089` (or use a "port check" app). If it doesn’t connect, the firewall or network is blocking 8089.
4. **SSL and self-signed cert**
- If the server log says **(TLS)**, iTAK must trust the cert: use **Upload server package** (download the zip from KestrelOS Settings) or run CoT without TLS and add the server with SSL disabled (see [Self-signed certificate](#2-self-signed-certificate-required-for-ssl)).
- If the server says **(plain TCP)**, in iTAK **disable** SSL.
5. **Where to look for logs**
- Same terminal where you ran `npm run dev` or `node .output/server/index.mjs`. If you use Docker/systemd, check that process’s stdout/stderr.
Once the connection reaches the server you’ll see at least: `[cot] client connected (TLS) from `.
---
- **Connection refused:** Ensure ports 3000 (web/API) and 8089 (CoT) are open on the server and in any firewall.
- **"Error authenticating" but you do see `[cot]` logs:** Username must be the KestrelOS **identifier** (login name) and password must match (local: login password; OIDC: ATAK password set in **Account**).
- **Authentication failed (OIDC user):** Set an **ATAK password** in KestrelOS under **Account**.
- **Devices not on KestrelOS map:** They appear only while sending position updates; they drop off after the TTL (~90 s) with no updates.
- **SSL:** If the server uses TLS (`.dev-certs/` or production cert), connect to port 8089 with SSL enabled in ATAK/iTAK.
---
## Summary
| Step | ATAK / iTAK |
|------|-------------|
| Add server | **QR:** KestrelOS **Settings** → scan TAK Server QR with iTAK/ATAK. Or add manually: **Host** = KestrelOS, **Port** = 8089 (CoT). |
| Self-signed SSL (iTAK) | **Settings** → Download **server package (zip)** → in iTAK: **Upload server package** and select it. Or run CoT without TLS (remove `.dev-certs`, restart) and add server with SSL disabled. |
| Auth | Enable “Use Authentication”; **Username** = KestrelOS identifier; **Password** = login password (local) or ATAK password (OIDC). |
| OIDC users | Set **ATAK password** once in KestrelOS **Account** before connecting. |
| Result | CoT is relayed between all connected TAK clients; positions show on the KestrelOS web map as amber markers. |