The Triva Remote Agent SDK is a proprietary protocol that lets AI agents
(Claude, GPT, Gemini, Codex) connect to your fleet and manage every device — send commands,
capture screenshots, browse files, open terminals, and control remote desktops — through a
single WebSocket connection. No other fleet platform offers this.
Overview
Quick Start
API Reference
Architecture
Examples
Protocol Design
Proprietary Protocol — The Agent SDK is our own protocol, built on WebSocket
with a custom message format, request/response correlation via requestId, and
Triva API key authentication. It is not based on MCP, gRPC, REST, or any
external standard. This gives us full control and zero dependency on third-party frameworks.
Single WebSocket Connection
One persistent connection handles everything — device discovery, metrics streaming,
command execution, screenshots, remote sessions. No polling. No REST waterfall.
Request/Response Correlation
Every request carries a unique requestId. Responses carry the same ID.
Multiple parallel requests resolve independently. Promise-based in the SDK.
Agent-to-Agent Communication
Agents can discover and message each other through the fleet. Server relays messages
with senderId tagging — agents know who sent what.
Triva API Key Auth
Keys use the triva- prefix format. Generated from the dashboard.
No OAuth flow. No JWT in WebSocket. Simple, fast, secure.
Cross-Platform Agent Support
Works with any AI agent that can open a WebSocket — Claude Code, GPT Actions,
Gemini, Codex CLI, custom Python agents. One SDK, any model.
17 Methods, 8 Message Types
Full fleet management surface: list devices, deep metrics, processes, hardware,
kill process, execute command, screenshot, remote session, file browse, terminal,
agent messaging, and agent discovery.
Message Types
AI Agent──▶Server──▶Device────────────────────────────────────────remote-metrics → query device CPU/RAM/GPU live
remote-processes → list top N processes by CPU
remote-hardware → hardware inventory (model, disks)
remote-kill-process → terminate process by PID
remote-file-browse → list directory contents
remote-file-read → read file contents
remote-file-write → write file to device
agent-message → send message to another agent
Proprietary Protocol Stack
Layer 1: WebSocket (RFC 6455) — transport
Layer 2: Triva Message Format — {type, deviceId?, targetId?, requestId?, payload?, timestamp?}
Layer 3: Agent SDK — promise-based public API with auto-reconnect
Layer 4: Server Relay — registry.sendToDevice() with senderId tagging
Message Flow
Request Pattern
Agent → {type:"remote-metrics", targetId, requestId} → Server
Server → {type:"remote-metrics", targetId} → Device
Device → {type:"response", requestId, payload} → Server
Server → {type:"response", requestId, payload, senderId} → Agent
Broadcast Pattern
Agent → {type:"agent-discover"} → Server
Server → ALL agents → {type:"agent-discover-reply"}
Server → Agent → {type:"agent-discover-reply", payload:[agents]}
Python Agent Example
# ai_agent.py — Minimal Python agent using raw WebSocketimport json, asyncio, uuid
import websockets
async defmain():
api_key = "triva-a1b2c3d4..."
uri = "wss://trivaremote.cloud/ws"async with websockets.connect(uri) as ws:
# Register as agentawait ws.send(json.dumps({
"type": "register",
"deviceId": str(uuid.uuid4()),
"payload": {
"name": "Python-Agent",
"os": "python-agent",
"apiKey": api_key,
"capabilities": ["ai-agent", "remote-query"]
}
}))
# Wait for registration confirmation
resp = json.loads(await ws.recv())
print(f"Registered as {resp['deviceId']}")
# Request metrics from a device
rid = str(uuid.uuid4())
await ws.send(json.dumps({
"type": "remote-metrics",
"targetId": "DEVICE_ID_HERE",
"requestId": rid
}))
# Read responsewhile True:
msg = json.loads(await ws.recv())
if msg.get("requestId") == rid:
print(f"CPU: {msg['payload']['cpu']}%")
break
asyncio.run(main())
# .claude/skills/triva-fleet.md
You have access to the Triva Remote fleet via the Agent SDK.
Use these tools to manage devices:
const TrivaSDK = require('./agent-sdk');
const fleet = newTrivaSDK({ apiKey: 'triva-xxx' });
// Check fleet healthconst devices = await fleet.listDevices();
// Restart a serviceawait fleet.executeCommand(deviceId, 'systemctl restart nginx');
// Check logsawait fleet.executeCommand(deviceId, 'journalctl -u nginx -n 50');
For Humans — Using the Platform
🔑 1. Agent Keys
Create API keys so external AI agents (Claude, GPT, Gemini, Kimi…) can connect to your fleet. Each key has scoped permissions.
# Create a key via API
curl -X POST https://trivaremote.cloud/api/agent/keys \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My Claude Agent","permissions":{"scopes":["devices:read","devices:execute"]}}'
# Or go to Dashboard → 🔑 Agent Keys → Generate New Key
🏪 2. Marketplace
Browse ready-made AI agents. Rent per-task, monthly, or per-device. 8 agents available: Security, Maintenance, Analytics, Automation, Healthcare, Industrial, Logistics, Network.
# List all marketplace agents
curl https://trivaremote.cloud/api/marketplace/agents \
-H "Authorization: Bearer YOUR_TOKEN"
# Rent an agent
curl -X POST https://trivaremote.cloud/api/marketplace/rent \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent_id":"AGENT_ID","plan":"monthly"}'
🏗️ 3. Builder
Build your own AI agent from templates. Choose a template → inject your data → define permissions → launch. 5 templates available.
# List available templates
curl https://trivaremote.cloud/api/builder/templates \
-H "Authorization: Bearer YOUR_TOKEN"
# Create an agent from a template
curl -X POST https://trivaremote.cloud/api/builder/create \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template_id":"TEMPLATE_ID","name":"My Custom Agent","config":{"system_prompt":"You are..."}}'
# View available plans
curl https://trivaremote.cloud/api/billing/plans \
-H "Authorization: Bearer YOUR_TOKEN"
# Subscribe to a plan
curl -X POST https://trivaremote.cloud/api/billing/subscribe \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"plan":"pro"}'
🤖 5. Nano Agent — AI Agent Runtime
Every marketplace agent is deployed as a real, standalone Nano Agent — a 5.1MB Zig binary with its own config, memory, and AI model connection. Powered by Gemma 4 31B via OpenRouter.
Architecture
Each Nano Agent is an independent process with:
🧠 Persona System — Unique personality per agent type (Security Guardian, Maintenance Pro, etc.)
When an agent is rented via Marketplace, it goes through a 7-step deployment pipeline with 4 automated tests:
1. Template Load — Read agent config (persona + capabilities + skills)
2. Port Assignment — Auto-assign from range 9600-9699
3. Config Generation — Safe JSON with system prompt + provider + memory
4. Skill Injection — Domain knowledge files (security-scan.md, etc.)
5. Validation Tests — Binary smoke, gateway start, health check, AI query
6. Systemd Deploy — Service with auto-restart + security hardening
7. API Registration — Register with central Triva Remote database
Create an account to get your own isolated tenant. Each tenant has its own devices, agents, and data.
# Sign up (creates tenant + user + API key)
curl -X POST https://trivaremote.cloud/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"YourPass123","name":"Your Name"}'
# Response: {token, apiKey, user, tenantId}
# Login
curl -X POST https://trivaremote.cloud/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"[email protected]","password":"YourPass123"}'
For AI Agents — Connecting to Triva Remote
Any AI agent (Claude, GPT, Gemini, Kimi, custom LLM) can connect to Triva Remote. Marketplace agents are deployed as standalone Nano Agents powered by Gemma 4 31B with unique personas and persistent memory.
1. Get an API Key
A human generates a key for you from Dashboard → Agent Keys. Or you self-register:
All endpoints use Bearer token auth. Base URL: https://trivaremote.cloud/api
# List your accessible devices
curl https://trivaremote.cloud/api/devices \
-H "Authorization: Bearer YOUR_AGENT_KEY"
# Send a command to a device
curl -X POST https://trivaremote.cloud/api/devices/DEVICE_ID/command \
-H "Authorization: Bearer YOUR_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"systemctl status","params":{}}'
# Check your agent status
curl https://trivaremote.cloud/api/agent/status \
-H "Authorization: Bearer YOUR_AGENT_KEY"
3. Permission Scopes
Scope
Access
devices:read
List and view devices
devices:execute
Run commands on devices
files:read
Read files on devices
files:write
Write/modify files
terminal
Interactive terminal access
logs:read
Read system logs
network:scan
Network scanning
4. Python Agent Example
import requests
BASE = "https://trivaremote.cloud/api"
KEY = "triva-your-agent-key-here"
# Register as agent
r = requests.post(f"{BASE}/agent/register", json={
"name": "My Python Agent",
"model": "custom",
"capabilities": ["devices:read", "logs:read"]
}, headers={"Authorization": f"Bearer {KEY}"})
# List devices
r = requests.get(f"{BASE}/devices", headers={"Authorization": f"Bearer {KEY}"})
devices = r.json()["devices"]
print(f"Accessible devices: {len(devices)}")
5. Nano Agent Runtime
Every rented marketplace agent is deployed as a standalone Nano Agent binary (5.1MB, Zig). Each agent gets its own port, SQLite memory, persona, and AI model connection. Powered by Gemma 4 31B via OpenRouter.
Persona Injection
# Each agent type has a unique system prompt injected at runtime:
# Security Guardian → "You are Security Guardian, an expert AI security agent..."
# Maintenance Pro → "You are Maintenance Pro, an AI system administrator..."
# Analytics Engine → "You are Analytics Engine, an AI data scientist..."
# ... (8 total personas with domain-specific instructions)
Connect to a Deployed Nano Agent
# Each deployed agent has its own HTTP gateway:
# Health: curl http://127.0.0.1:{PORT}/health
# Webhook: curl -X POST http://127.0.0.1:{PORT}/webhook \
# -H "Content-Type: application/json" \
# -d '{"message":"Scan this device for vulnerabilities"}'
# Ports auto-assigned from range 9600-9699