@mastractl/client

Typed REST client for the mastractl control plane.

⚠ Alpha — API surface may change between 0.7.x releases.

Install

npm install @mastractl/client

Usage

import { createClient } from "@mastractl/client";

const mastractl = createClient({
  baseUrl: process.env.MASTRACTL_URL ?? "http://127.0.0.1:3100",
  // one of: serviceToken (headless) or cookie (browser/session)
  serviceToken: process.env.MASTRACTL_SERVICE_TOKEN,
});

// List agents
const { agents } = await mastractl.agents.list("<company-id>");

// Hire an agent
const created = await mastractl.agents.hire("<company-id>", {
  id: "helper",
  name: "Helper",
  role: "Terse assistant",
  instructions: "Answer concisely.",
  model: { provider: "openrouter", id: "moonshotai/kimi-k2.5" },
  budget: { monthlyCents: 100 },
});

// Drive a heartbeat turn
const reply = await mastractl.agents.heartbeat("<company-id>", created.agentId, {
  userMessage: "hello",
});
console.log(reply.result);

Authentication

The client sends requests to your mastractl instance. Two auth modes:

1. Service token (headless scripts, CI) — serviceToken: "mct_...". Create one: mastractl mcp call ... or via the REST API.
2. Cookie — pass a cookie string for session-based auth (browser contexts).

Part of the mastractl SDK

| Package | Purpose | |---|---| | @mastractl/shared | Error primitives | | @mastractl/agent | AgentSpec types + BYO adapter | | @mastractl/client | Typed REST client (this package) |

Requires a running mastractl server. See the main README for setup.