Tendrl

Docs / Contact / sdks/nano-agent/api-reference

Nano Agent: API Reference

The Nano Agent communicates via JSON messages over a Unix socket. This page documents every supported message type and the socket protocol.

For shell-based testing, see the tendrl CLI client, which wraps these message types as subcommands.

Socket Protocol#

  1. Open a AF_UNIX / SOCK_STREAM connection to the socket
  2. Write one or more JSON messages (UTF-8 encoded)
  3. Optionally read the response (for wait: true, msg_check, state_read)
  4. Close the connection when you're done

The socket is stateless: a single connection can carry multiple messages, so you can either open a fresh connection per message or keep one open and stream many. When you send a request that returns data (wait: true, msg_check, state_read), read its response before sending the next message on the same connection.

Socket Paths#

Platform Path
Linux/macOS /var/lib/tendrl/tendrl_agent.sock
Windows C:\ProgramData\tendrl\tendrl_agent.sock

Message Types#

publish#

Send data to Contact. Messages are queued and batched by default.

json

{
  "msg_type": "publish",
  "data": { ... },
  "dest": "entity-name",
  "context": {
    "tags": ["tag1", "tag2"],
    "wait": false,
    "entity": "entity-id"
  }
}
Field Required Description
msg_type Yes Must be "publish"
data Yes JSON object or string payload
dest No Target entity name
context.tags No Routing tags (max 10)
context.wait No true to wait for server response
context.entity No Entity identifier

heartbeat#

Send system metrics. Sent directly (not batched).

json

{
  "msg_type": "heartbeat",
  "data": {
    "mem_free": 1024.0,
    "mem_total": 4096.0,
    "disk_free": 50000.0,
    "disk_size": 100000.0
  }
}
Field Type Description
mem_free float Free memory (MB)
mem_total float Total memory (MB)
disk_free float Free disk space (MB)
disk_size float Total disk space (MB)

state_new#

Create or replace the entity's state table (PUT).

json

{
  "msg_type": "state_new",
  "data": { "key": "value" }
}

state_update#

Merge data into the existing state table (PATCH).

json

{
  "msg_type": "state_update",
  "data": { "key": "new_value" }
}

state_read#

Retrieve the entity's current state table.

json

{
  "msg_type": "state_read"
}

Response:

json

{
  "statusTable": { "key": "value" }
}

msg_check#

Poll for incoming messages.

json

{
  "msg_type": "msg_check",
  "context": { "limit": 5 }
}

Response (array of messages):

json

[
  {
    "msg_type": "publish",
    "data": { ... },
    "tags": ["tag1"],
    "source": "account:region:entity:name",
    "timestamp": "2025-01-15T10:30:45Z"
  }
]

Returns HTTP status 204 (as a string) when no messages are pending.

Error Responses#

All errors follow this format:

json

{
  "status": "error",
  "message": "Description of the error"
}
Error Message Cause
Queue full, try again later Message queue at capacity
Too many tags provided; maximum is 10 More than 10 tags in context
Unknown message type msg_type not recognized

Batching Behavior#

The agent batches messages using dynamic sizing based on system load:

The agent handles all communication with Contact over HTTPS on your behalf. Your application interacts with the agent through the local Unix socket interface documented above; you never call Contact's HTTP API directly.

← Back to Contact docs