API Reference

Overview

TokForge includes a built-in MetricsService — an HTTP API for remote device control, monitoring, and benchmarking. It runs as an embedded NanoHTTPD server accessible from any app or computer on the same network (or via ADB port forwarding).

This API enables AI agents, developers, and external tools to:

• Discover device hardware capabilities
• List, load, and unload inference models
• Run inference tests and benchmarks
• Manage conversations and character cards
• Control app navigation and UI
• Export/import configuration and benchmark results
• Monitor performance metrics in real time

Setup

Enabling the API Server

The API server is disabled by default. To enable it:

1. Open TokForge → Settings → scroll to Advanced
2. Toggle "Metrics Server" → ON
3. Choose Bind Host:
   • Localhost only (127.0.0.1) — accessible only from the device itself or via ADB port forwarding. Use this for development and testing.
   • All interfaces (0.0.0.0) — accessible from any device on the local network (e.g., http://192.168.1.100:8088/health). Use this for remote control from another computer, AI agents, or Home Assistant.
4. Set Port (default: 8088)
5. Tap "Regenerate" next to the API Key field to generate a new auth token, or enter your own

Security note: When using "All interfaces", the API is accessible to anyone on your network. Always use a strong API key and avoid exposing the port to the internet.

Network Binding Behavior

Build Type	Localhost (127.0.0.1)	All Interfaces (0.0.0.0)
Debug	Auth bypassed (no token needed)	Auth required
Release	Auth required	Forced to 127.0.0.1 (security hardening)

In release builds, the server always binds to 127.0.0.1 regardless of the setting. To access the API from another device with a release build, use ADB port forwarding (see below).

Architecture

Server	NanoHTTPD (Java HTTP library)
Default port	8088 (configurable in Settings → Advanced)
Transport	HTTP/1.1
Auth	Bearer token (configured in Settings → Advanced → API Key)
Encoding	JSON (application/json)
Response Format	JSON object with status, data, or error fields

Authentication

Getting Your API Key

From the app (recommended):

1. Open Settings → Advanced → Metrics Server section
2. Your API key is displayed in the "Metrics Auth Token" field
3. Tap "Regenerate" to create a new key at any time
4. Copy the token and use it in your API requests

Programmatically (debug builds only):

# Token is logged at startup (debug builds only, truncated for security)
adb logcat -s MetricsServer | grep "Auth token"

# Or retrieve via DebugReceiver (debug builds only)
adb shell am broadcast -a dev.tokforge.DEBUG_ACTION \
    -n dev.tokforge/.debug.DebugReceiver \
    --es command get_auth_token
adb shell run-as dev.tokforge cat files/.auth_token

Via the API itself:

# Rotate the token and receive the new one in the response
curl -X POST -H "Authorization: Bearer CURRENT_TOKEN" \
     http://localhost:8088/control/rotate-auth-token
# Response: {"status":"ok", "auth_token":"NEW_TOKEN_HERE", "token_rotated":true}

Using the Token

All POST, DELETE, and most PUT endpoints require authentication. A few read-only endpoints (/health, /version, /metrics, /state/hardware) are accessible without auth.

Include the token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST http://DEVICE_IP:8088/control/load-model \
     -d '{"model_id": 1}'

Missing or invalid tokens return 401 Unauthorized:

{
  "error": "Unauthorized — provide Bearer token in Authorization header"
}

Unauthenticated Endpoints

These endpoints are accessible without a token (useful for health checks and monitoring):

Endpoint	Description
GET /health	Server status, loaded models, uptime
GET /version	App version, build type, device info
GET /metrics	Model load state
GET /state/hardware	SoC, RAM, GPU, recommended config

Connecting to the API

Same Network (All Interfaces mode)

If the server is bound to 0.0.0.0 (debug builds), connect directly using the device's IP:

# Find device IP in Settings → About Phone → Status → IP Address
curl http://192.168.1.100:8088/health

ADB Port Forwarding (Localhost mode or Release builds)

Forward the device port to your computer:

# Single device
adb forward tcp:8088 tcp:8088
curl http://localhost:8088/health

# Multiple devices — use unique local ports
adb -s DEVICE1_SERIAL forward tcp:8088 tcp:8088
adb -s DEVICE2_SERIAL forward tcp:8089 tcp:8088
adb -s DEVICE3_SERIAL forward tcp:8090 tcp:8088

On-Device Access

From the device itself (e.g., Termux, or another app):

curl http://127.0.0.1:8088/health

Use a unique local port per active test script/process. Reusing the same local port (for example two scripts both using tcp:8088) will overwrite forwarding and cause intermittent control-plane disconnects.

1. Health & Status

2. State Endpoints

3. Model Endpoints

4. Configuration

5. Inference & Generation

6. Conversations

7. Characters

8. Benchmarks

9. Debug

10. UI Control

Workflow Examples

7-Step AI Agent Workflow

A complete example of using the TokForge API to build an autonomous AI agent:

Step 1: Verify Device Readiness

curl -s http://localhost:8088/health | jq '.mnn_loaded'
# Output: true (device ready)

Step 2: List Available Models

curl -s -H "Authorization: Bearer TOKEN" \
     http://localhost:8088/models | jq '.data[] | .name'

Step 3: Load a Model

curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"model_id": 3}' \
     http://localhost:8088/control/load-model

Step 4: Create a Conversation

curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"title": "Agent Session", "backend": "mnn"}' \
     http://localhost:8088/control/create-conversation
# Returns: {"status":"ok", "id": "conv_12345"}

Step 5: Send Message and Get Response

curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message": "What is 2+2?"}' \
     http://localhost:8088/conversations/conv_12345/send
# Returns: {"status":"ok", "response": "2+2 equals 4."}

Step 6: Monitor Performance

curl -s http://localhost:8088/performance | jq '.last_generation_stats'
# Shows: tokens/sec, memory usage, thermal status

Step 7: Run Benchmark and Export

curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Benchmark prompt", "num_tokens": 100}' \
     http://localhost:8088/benchmark/run

# Export results
curl -s http://localhost:8088/benchmark/export > results.json

Error Handling

Code	Meaning
200	Success
400	Bad Request (invalid parameters)
401	Unauthorized (missing or invalid auth token)
404	Not Found (resource doesn't exist)
408	Timeout (operation took too long)
409	Conflict (another operation already running)
500	Internal Server Error

Rate Limits

The API applies per-token rate limits to prevent abuse:

Endpoint Type	Limit	Window
Read (GET, unauthenticated)	100 requests	1 minute
Read (GET, authenticated)	200 requests	1 minute
Write (POST, DELETE)	50 requests	1 minute
Benchmark operations	5 concurrent	Continuous
Model downloads	1 concurrent	Continuous

Hitting the limit returns 429 Too Many Requests. Retry-After header indicates seconds to wait.

Security

• Localhost only by default: Server binds to 127.0.0.1 in release builds, not accessible over network without ADB
• Auth tokens: Generated per-session, configured in Settings. Treat as secrets. Rotate regularly with /control/rotate-auth-token
• No HTTPS: Uses plain HTTP over ADB tunnel. ADB provides the security boundary.
• Debug mode only: API is only available in debug builds (BuildConfig.DEBUG) or when explicitly enabled.
• Network binding: Release builds force localhost binding regardless of settings. Use ADB port forwarding for remote access.
• CORS: Not applicable (native Android app, no browser context)
• Input validation: All parameters validated server-side. Untrusted input sanitized before use.