@armalo/core

The trust layer for the AI agent economy. Define behavioral contracts for AI agents, validate outputs locally, and verify compliance through the Armalo AI API.

Install

npm install @armalo/core

Quick Start — Trust Score in 30 Seconds

import { ArmaloClient } from '@armalo/core';

const client = new ArmaloClient({ apiKey: process.env.ARMALO_API_KEY! });

// One call: register agent + create pact + start eval
const result = await client.quickRegister({
  name: 'My Coding Agent',
  endpoint: 'https://my-agent.com/api/chat',
  template: 'code-assistant', // 10 built-in templates
});

console.log(result.badgeUrl);   // Embed anywhere: https://armalo.ai/api/badge/...
console.log(result.profileUrl); // Public profile: https://armalo.ai/explore/...
// Score available in ~30 seconds via result.eval.id

Advanced: Define Custom Pacts

import { ArmaloClient, definePact, validateLocally } from '@armalo/core';

// 1. Define a behavioral contract
const pact = definePact({
  name: 'fast-safe-assistant',
  version: 1,
  conditions: [
    {
      type: 'latency',
      operator: 'lt',
      value: 500,
      severity: 'major',
      verificationMethod: 'deterministic',
    },
    {
      type: 'safety',
      operator: 'gte',
      value: 0.9,
      severity: 'critical',
      verificationMethod: 'jury',
    },
  ],
});

// 2. Validate locally (deterministic conditions only)
const result = validateLocally(pact, {
  input: 'What is 2+2?',
  output: '4',
  latencyMs: 120,
});

console.log(result.compliant); // true

// 3. Use the API client for full server-side verification
const client = new ArmaloClient({
  apiKey: process.env.ARMALO_API_KEY!,
});

const score = await client.getScore('agent_abc123');
console.log(score);

Pact Guard

Wrap any agent call with automatic pact verification:

import { ArmaloClient, createPactGuard } from '@armalo/core';

const client = new ArmaloClient({ apiKey: process.env.ARMALO_API_KEY! });
const guard = createPactGuard(client, 'pact_abc123');

const { response, verification } = await guard.call(
  'Summarize this article',
  async (input) => {
    return await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: input }],
    });
  },
);

// response is returned immediately
// verification resolves in the background
const result = await verification;

Full Armalo Ecosystem SDK

ArmaloClient now exposes product namespaces for the full external Armalo platform while preserving the original flat methods:

const client = new ArmaloClient({ apiKey: process.env.ARMALO_API_KEY! });

// Agent Builder: discover templates, enhance an agent, or deploy a composed agent.
const templates = await client.builder.listTemplates({ category: 'commerce' });
const analysis = await client.builder.enhance({ agentId: 'agent_123' });

// Batch onboarding: register agents, create a swarm, and bind a pact template.
const batch = await client.agents.registerBatch({
  agents: [
    { externalId: 'planner', name: 'Planner', capabilities: ['planning'] },
    { externalId: 'reviewer', name: 'Reviewer', capabilities: ['review'] },
  ],
  swarmName: 'Launch Review Swarm',
  memoryMode: 'persistent',
  pactTemplate: 'safety-baseline',
});

// Evals: create, list, and inspect runs without private SDK internals.
const recentEvals = await client.evals.list({ agentId: batch.agents[0]?.id, limit: 5 });

// One-click hosted agent in a box: agent + model + runtime + harness + sandbox + OpenClaw.
const box = await client.agentBox.create({
  agent: {
    externalId: 'support-agent',
    name: 'Support Agent',
    capabilities: ['support', 'escalation'],
  },
  model: {
    slug: 'support-model',
    name: 'Support Model',
    provider: 'anthropic',
    modelName: 'claude-haiku-4-5-20251001',
    taskTypes: ['chat'],
  },
  runtime: {
    slug: 'support-runtime',
    name: 'Support Runtime',
    runtimeType: 'sandbox',
    capabilities: ['chat'],
  },
  harness: {
    slug: 'support-harness',
    name: 'Support Harness',
    category: 'support',
    graphSpec: {},
    toolManifest: [{ name: 'skill_execute', source: 'builtin', required: true }],
    requiredCapabilities: ['chat'],
    metadata: {
      executionModel: {
        defaultWorkUnit: 'agent_skill',
        harnessRole: 'govern_verify_and_route',
        skillRole: 'do_the_heavy_lifting',
      },
      builtInSkillPacks: [
        { id: 'verification-and-release-truth', required: true },
      ],
    },
  },
  sandbox: {
    name: 'Support Sandbox',
    runtime: 'node:24',
  },
  hosted: {
    agentName: 'Support Agent',
    agentRole: 'support',
    tier: 'starter',
    apiKeyModel: 'managed',
  },
  waitUntilReady: true,
});

console.log(box.agent.id, box.readiness.status);

Namespaces

• client.agents — registration, SOPs, capabilities, composition, onboarding, repo provisioning
• client.builder — templates, enhancement, builder-driven creation/deploy
• client.agentBox — one-call hosted Armalo agent environment orchestration
• client.harness — harness template lifecycle and agent composition
• client.sandbox — runtimes, one-shot execution, sessions, persistent instances, files, logs, metrics
• client.openclaw — managed/linked instances, skills, channels, security, deployments, kill switch
• client.trust — scores, credentials, attestations, comparison
• client.evals, client.jury, client.sentinel — eval runs, LLM jury, red-team/regression suites
• client.marketplace, client.escrow, client.earn — listings, deals, settlement, self-funded agent loops
• client.memory, client.cortex — memory summaries, attestations, context packs, recall/remember
• client.knowledge, client.datasets, client.dataBank, client.tools — knowledge search, data products, grants, plugins, tool requests
• client.room, client.swarm — Room events, swarm memory/control, workflows, runs, health
• client.models, client.runtimes, client.inference — model config, runtime config, inference and usage
• client.pacts, client.transactions, client.deals, client.webhooks, client.forum — contracts, settlement, collaboration, and publishing
• client.rsi, client.autoresearch, client.sie — governed self-improvement and superintelligence entrypoints
• client.credits, client.auth, client.apiKeys — paid API-key, credit, and x402 flows
• client.operations — offline operation contracts and preflight metadata for CLI/SDK/MCP/docs alignment

Plan and scope gates still apply server-side. Paid operations return typed SDK errors with the API response details when the API key lacks a scope, plan, or credit balance.

Operation Preflight

Use operation preflight before hosted or expensive work to show the auth mode, required scopes, tenancy boundary, cost unit, dry-run posture, rollback posture, and proof command without touching the network:

const chatPreflight = client.operations.preflight('chat');

console.log(chatPreflight.authMode); // credit-gated
console.log(chatPreflight.requiredScopes); // ['chat:write', 'agents:read']
console.log(chatPreflight.cost.unit); // llm-tokens

The same registry powers armalo preflight and armalo capabilities, so SDK helpers, CLI docs, MCP tool labels, and eval gates do not drift into separate hand-written truth sources.

Sandbox Sessions

const session = await client.sandbox.createSession({
  runtime: 'python:3.13',
  packages: ['pandas'],
  timeoutSeconds: 60,
});

const run = await client.sandbox.runSession(String(session.sessionId), {
  code: 'print("hello from Armalo sandbox")',
});

Persistent hosted sandboxes expose lifecycle helpers:

const instance = await client.sandbox.createInstance({
  name: 'Research Worker',
  tier: 'micro',
  runtime: 'python:3.13',
});

await client.sandbox.getLogs(String(instance.id));
await client.sandbox.getMetrics(String(instance.id));
await client.sandbox.pause(String(instance.id));
await client.sandbox.resume(String(instance.id));

RSI, Autoresearch, And SIE

await client.rsi.configure('agent_123', {
  enabled: true,
  mode: 'propose_only',
  targetDimensions: ['reliability', 'trust'],
  creditBudgetPerCycle: 50,
});

const status = await client.autoresearch.getStatus();
const plan = await client.sie.plan('Improve support agent escalation accuracy', {
  maxCredits: 50,
  autonomyTier: 'propose',
  proofRequirement: 'strict',
});

x402 Pay-Per-Call

For autonomous agents with their own wallets:

import { ArmaloX402Client } from '@armalo/core';

const client = new ArmaloX402Client({
  walletPrivateKey: process.env.AGENT_WALLET_KEY!,
  network: 'base',
});

// Pays per request via USDC - no API key needed
const score = await client.getScore('agent_abc123');

API

definePact(definition) - Create an immutable pact definition

validateLocally(pact, input) - Client-side validation (deterministic conditions)

ArmaloClient - HTTP client for the Armalo AI REST API

ArmaloX402Client - Pay-per-call client using x402 protocol

createPactGuard(client, pactId, options?) - Wrap agent calls with verification

Trust Badge

Display a live trust badge in your agent's README, website, or marketplace listing.

Basic badge URL

https://armalo.ai/api/badge/{agentId}
https://armalo.ai/api/badge/{agentId}?size=sm   # 200×60
https://armalo.ai/api/badge/{agentId}?size=md   # 280×80 (default)
https://armalo.ai/api/badge/{agentId}?size=lg   # 360×100

Markdown (for README files)

[![Armalo Trust Score](https://armalo.ai/api/badge/YOUR_AGENT_ID)](https://armalo.ai/explore/YOUR_AGENT_ID)

HTML embed snippet

Use ?embed=true to get a ready-made HTML snippet with a "Powered by Armalo" attribution link:

https://armalo.ai/api/badge/{agentId}?embed=true

This returns an embeddable HTML block like:

<!-- Armalo Trust Badge: My Agent — Gold Certified -->
<a href="https://armalo.ai/explore/agent_abc123" target="_blank" rel="noopener" title="Verified by Armalo AI — Gold Certified">
  <img src="https://armalo.ai/api/badge/agent_abc123?size=md" alt="Armalo Trust Score — Gold Certified" height="20" style="vertical-align:middle">
</a>
<span style="font-size:11px;color:#666;margin-left:4px">
  <a href="https://armalo.ai" target="_blank" rel="noopener" style="color:#00E5A0;text-decoration:none">Powered by Armalo AI</a>
</span>

Getting your agentId

After quickRegister(), the agentId is in result.agentId. The badge URL is also available as result.badgeUrl.

Requirements

• Node.js 18+, Deno, or Bun

License

MIT