Quickstart

1. Get an API Key

Sign up at swarmlord.ai and create an API key from the dashboard.

2. Install the SDK

npm

npm install swarmlord

pnpm

pnpm add swarmlord

bun

bun add swarmlord

3. Send Data, Get Artifacts

Start with a CSV:

month,revenue,users
Jan,42000,1200
Feb,48000,1350
Mar,51000,1580
Apr,61000,1800
May,58000,2100
Jun,72000,2450

Create a file called analyze.ts:

import { createClient } from "swarmlord";
import { readFileSync, writeFileSync } from "fs";

// prepare
const client = createClient({ apiKey: process.env.SWARMLORD_API_KEY! });
const session = await client.agent("build").createSession();
const csv = readFileSync("data.csv");

// run agent
await session.send(
    {
        parts: [
            {
                type: "text",
                text: "Analyze this CSV. Create a matplotlib chart saved as /workspace/chart.png and a summary report at /workspace/report.html.",
            },
            {
                type: "file",
                url: `data:text/csv;base64,${csv.toString("base64")}`,
                mime: "text/csv",
                filename: "data.csv",
            },
        ],
    },
    { onText: delta => process.stdout.write(delta) }
);

// download artifacts
const chart = await session.getFileBuffer("/workspace/chart.png");
writeFileSync("chart.png", new Uint8Array(chart));

const report = await session.getFile("/workspace/report.html");
writeFileSync("report.html", report);

console.log("\nDownloaded chart.png and report.html");
await session.end();

4. Run It

First, set your API key in your environment (e.g. in a .env file):

export SWARMLORD_API_KEY="your-key-here"

Then run the script:

bun analyze.ts

You'll see the agent stream its work in real-time — reading the CSV, writing Python code, generating a chart, and building an HTML report. When it's done, chart.png and report.html are on your machine.

What Just Happened?

1. createClient authenticated you with the swarmlord API.
2. client.agent("build") created a handle to an agent with all built-in tools enabled — shell, file I/O, web search, browser, and more.
3. createSession() spun up a fresh session with its own Linux sandbox.
4. session.send() uploaded the CSV and streamed the agent's response via onText.
5. getFileBuffer / getFile pulled the generated artifacts from the sandbox to your local disk.
6. session.end() cleaned up the session and its sandbox.

Next Steps

Browser Automation

Screenshot a live webpage and download the PNG.

Clone & Summarize

Clone a repo and summarize its recent commits.

Tools

13 built-in tools — enable or disable per agent.

Sessions

Multi-turn conversations, resuming, forking.