kestrelos/docs/atak-itak.md

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).

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:

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:

echo '<event><detail><auth username="itak" password="yourpassword"/></detail></event>' | \
  openssl s_client -connect localhost:8089 -quiet 2>/dev/null

If the server runs without TLS (plain TCP), use:

echo '<event><detail><auth username="itak" password="yourpassword"/></detail></event>' | \
  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 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).
   • 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 <ip>.

---

• 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.