Programmatic control for agents

TrueTick is built to be driven by software, not just clicked in a panel. AI agents, Discord bots, and automation scripts get the same surface: full server lifecycle, RCON, files, backups, and — the part that matters for autonomous decisions — honest live metrics you can actually trust.

Why it fits agents

• Metered + scale-to-zero means an agent can create servers liberally and only pay for the minutes they run. Spin one up, do the work, tear it down — see Ephemeral test server.
• Real TPS/MSPT means an agent can make data-driven decisions (restart? scale? alert?) instead of trusting a fabricated green dashboard.
• Scoped keys let you give an agent exactly the capabilities it needs and nothing more — e.g. a read-only monitoring bot gets servers:read only. See Authentication.

Two ways to connect

Direct API / SDK

Give the agent a scoped ttk_ key and let it call the API (directly or via the SDK). A minimal autonomous loop:

import { TrueTickClient } from "@truetick/sdk";
const client = new TrueTickClient(); // TRUETICK_API_KEY (scoped to what the agent may do)
 
async function ensureHealthy(id: string) {
  const s = await client.servers.get(id);
  if (s.state !== "running") {
    await client.servers.start(id);              // wake it
    return;
  }
  const m = await client.servers.metrics(id);
  // `live` gates tick data (MSPT, players) — NOT specifically a TPS reading.
  // tpsSource is the gate for the number itself: UNSPECIFIED means no reading
  // exists (first poll after a wake, or a parked empty world), and `tps` is a
  // zero VALUE there. Restarting a healthy server on that zero is the exact
  // mistake this field exists to prevent.
  const measured = m.tpsSource === "TPS_SOURCE_MEASURED" || m.tpsSource === "TPS_SOURCE_CORE";
  if ((measured && m.tps < 18) || m.tickStatus === "lagging") {
    await client.console.run(id, "say performance degraded — restarting");
    await client.servers.restart(id);             // act on a *real* signal
  }
}

MCP (Model Context Protocol)

For LLM agents, the @truetick/mcp server exposes the API as tools an assistant can call directly — create_server, start_server, run_command, get_server_metrics, and more. Point the MCP server at a scoped key and your agent can manage servers in natural language. See the MCP library page for the tool catalog and setup.

Patterns that work well

• Provision-test-destroy — create an ephemeral server, run a task, delete it in a finally.
• Health-gated actions — read metrics and only act when tpsSource says a reading exists and TPS crosses a real threshold. Don't act on stale/empty metrics (honest empty states exist precisely so you don't) — a tps of 0 under TPS_SOURCE_UNSPECIFIED is an absence, not a stall.
• Trend, not one poll — GET /v1/servers/{id}/tick-history gives minute buckets with a samples count and lagging flag, so an agent can tell "bad for the last twenty minutes" from "one bad poll."
• RCON for structured control — console.run(id, "...") for arbitrary commands; structured player management (whitelist/op/ban/kick) has dedicated servers:write endpoints in the API Reference.
• Event push, with polling as the fallback — configure a Discord alert webhook per server so the platform notifies you on TPS drops. A server with no live tick metrics gets no alert, so keep the poll running rather than relying on the push alone.

Offline-friendly behavior

Because servers are scale-to-zero, a hibernated server still responds to a server-list ping (with a MOTD + sleep line) and wakes automatically when a player joins — no agent needs to be online to bring it up for players. Your agent can stay offline and let wake-on-join handle the player path, then reconcile state on its next run. When the agent does need a server up on its own schedule, an explicit start triggers the same boot.