swarmlord

TypeScript SDK and CLI for Swarmlord — deploy cloud AI agents.

Install

npm install swarmlord

Two Tools, One Package

Swarmlord ships a CLI for building and deploying agents, and a TypeScript SDK for using them from your app. Same npm install, different concerns.

| Concern | Tool | Example | | ---------------- | ---- | ------------------------------------------------- | | Define an agent | CLI | swarmlord.jsonc + AGENTS.md | | Deploy / manage | CLI | swarmlord deploy, swarmlord pause | | Create sessions | SDK | client.agent("support-bot").createSession() | | Run tasks | SDK | client.agent("reviewer").run("Analyze this PR") | | Stream responses | SDK | session.send("...", { onText }) |

CLI — Build and Deploy Agents

Define agents as config files. Deploy with one command. No TypeScript required.

npx swarmlord init my-bot -n my-bot -t slack
cd my-bot
npx swarmlord run "Hello, test this agent"
npx swarmlord deploy

Each agent is a directory:

my-bot/
├── swarmlord.jsonc   # Config: model, trigger/schedule, tools, permissions
├── AGENTS.md         # Always-loaded instructions
├── tools/            # Custom tools (TypeScript or Python)
├── skills/           # On-demand knowledge (loaded via skill tool)
├── files/            # Pre-loaded workspace files
└── .gitignore

CLI Commands

| Command | What it does | | ---------------------------- | --------------------------------------------------- | | swarmlord init | Scaffold a new agent directory | | swarmlord run "prompt" | Test an agent locally (ephemeral session) | | swarmlord deploy | Deploy to production (trigger or schedule) | | swarmlord auth login | Authenticate with your API key | | swarmlord list | List all deployed agents | | swarmlord status | Show agent details | | swarmlord logs | Recent sessions for an agent | | swarmlord pause / resume | Disable / enable a trigger or schedule | | swarmlord destroy | Delete a deployed agent | | swarmlord trigger | Manually fire a scheduled agent | | swarmlord download | Download workspace files from a session | | swarmlord validate | Validate config, tools, and optionally check remote | | swarmlord test | Run custom tools locally with test input | | swarmlord test-integration | Simulate a webhook event and stream the agent run | | swarmlord secret | Manage encrypted secrets for tools and integrations |

See the CLI Reference for the full config format and skills system.

SDK — Use Deployed Agents from TypeScript

Deploy agents with the CLI, then reference them by name from your app.

Quick Start

import { createClient } from "swarmlord";

const client = createClient({ apiKey: process.env.SWARMLORD_API_KEY! });

const session = await client.agent("support-bot").createSession();

await session.send("Help me with a billing issue", {
    onText: delta => process.stdout.write(delta),
});

await session.end();

Agents

client.agent(name) references a deployed agent. The name comes from the name field in swarmlord.jsonc. All configuration — model, tools, instructions, skills, workspace files — is resolved from the deployment.

const bot = client.agent("support-bot");
const session = await bot.createSession({ title: "Ticket #1234" });

You can override settings per-agent-handle if needed:

const reviewer = client.agent({
    name: "code-reviewer",
    model: "google/gemini-3-flash-preview",
});

Sessions — Interactive Conversations

Sessions are stateful, multi-turn, and persistent. The agent's workspace (Linux container with your deployed files and skills) is seeded automatically.

const session = await bot.createSession({ title: "Build Todo App" });

// Callback API
const result = await session.send("Create a REST API with Hono", {
    onConnect: () => console.log("Connected"),
    onDisconnect: () => console.log("Reconnecting..."),
    onText: delta => process.stdout.write(delta),
    onReasoning: delta => { /* reasoning tokens */ },
    onToolStart: part => console.log(`[tool] ${part.tool}`),
    onToolComplete: part => console.log(`[done] ${part.tool}`),
    onToolError: (part, error) => console.error(`[error] ${part.tool}: ${error}`),
    onStepFinish: (tokens, cost) => console.log(`$${cost.toFixed(4)}`),
    onAttachment: file => console.log(`File: ${file.filename}`),
    onPermission: async req => "once", // "once" | "always" | "reject"
    onStatus: status => console.log(`Status: ${status}`),
    onError: err => console.error(err),
});

// Continue the conversation
await session.send("Now add authentication");

// Async iterator for full control
for await (const event of session.stream("Add tests")) {
    if (event.type === "text-delta") process.stdout.write(event.delta);
}

// Send file attachments
await session.send({
    parts: [
        { type: "text", text: "Analyze this CSV." },
        { type: "file", url: `data:text/csv;base64,${csvBase64}`, mime: "text/csv", filename: "data.csv" },
    ],
});

// Direct sandbox access (no LLM)
const shellResult = await session.shell("npm test");
console.log(shellResult.stdout);
console.log(`Exit code: ${shellResult.exitCode}`);

const file = await session.getFile("/workspace/output.json");
const image = await session.getFileBuffer("/workspace/chart.png");

// Session inspection
const info = await session.getInfo();
const messages = await session.getMessages();
const metrics = await session.getMetrics();
const todos = await session.getTodos();
const artifact = await session.getArtifact("report");

// Metadata
await session.update({ title: "New Title", archived: true });

// Lifecycle
await session.summarize(); // compact context
await session.revert(messageId); // undo
await session.abort(); // cancel current turn
await session.end(); // clean up

Resume or Fork

// Resume from another process
const session = client.session("existing-session-id");
await session.send("Continue where we left off");

// Fork to try an alternative
const fork = await bot.forkSession("session-to-fork");
await fork.send("Try a different approach");

Tasks — Fire-and-Forget

Launch a task, walk away. The agent runs in the cloud.

const task = await bot.run("Refactor the auth module");

// Poll manually
const status = await task.poll(); // "accepted" | "busy" | "compacting" | "idle" | "error"

// Or block until done (default timeout: 600_000ms / 10 minutes)
const result = await task.result({ timeoutMs: 300_000 });
console.log(result.text);

// Cancel if needed
await task.cancel();

// Or use webhooks
const task = await bot.run("...", {
    webhook: "https://my-app.com/hooks/done",
});

// Resume from another process
const resumed = client.task(taskId);

Pipelines

Pipelines run multi-phase workflows where each phase produces artifacts consumed by later phases.

import { Pipeline } from "swarmlord";

const sprint = Pipeline.define({
    name: "research-sprint",
    phases: [
        {
            name: "research",
            prompt: vars => `Research the market for ${vars.idea}`,
            outputs: ["market-research.md"],
        },
        {
            name: "analysis",
            prompt: "Analyze the research and produce a strategy",
            outputs: ["strategy.md"],
        },
    ],
});

const result = await sprint.run(client.agent("my-agent"), {
    vars: { idea: "AI-powered recipe app" },
    on: {
        phaseStart: p => console.log(`Starting: ${p.name}`),
        text: (p, delta) => process.stdout.write(delta),
    },
});

console.log(result.report());

Listing Resources

const sessions = await client.listSessions({ limit: 20, archived: false });
const agents = await client.listDeployedAgents();
const schedules = await client.listSchedules();
const triggers = await client.listTriggers();
const { data: models } = await client.listModels();

Schedules and Triggers

const schedule = client.schedule("schedule-id");
await schedule.trigger(); // manually fire
await schedule.pause();
await schedule.resume();
await schedule.update({ cron: "0 10 * * 1-5" });
await schedule.delete();

const trigger = client.trigger("trigger-id");
const info = await trigger.getInfo();
await trigger.pause();
await trigger.resume();
await trigger.update({ events: ["app_mention"] });
await trigger.delete();

Configuration

const config = await client.getConfig();
await client.updateConfig({ model: "anthropic/claude-sonnet-4.6" });

Types

import type {
    AgentHandle,
    SessionHandle,
    TaskHandle,
    AgentConfig,
    AgentEvent,
    SendResult,
    TaskResult,
    TaskStatus,
    StreamCallbacks,
    SessionInfo,
    SessionMetrics,
    ScheduleInfo,
    TriggerInfo,
    ShellResult,
    Part,
    ToolPart,
    Tokens,
    MessageInput,
    Pipeline,
    PipelineDef,
    PipelineResult,
    PipelineCallbacks,
} from "swarmlord";