@ easybits. cloud/ sdk

用于AI代理的EasyBits云的被打入HTTP客户端——沙盒,网络,文件,SQL数据库,文档和应用程序托管.

EasyBits是云AI代理已经知道如何使用:在被隔离的"鞭炮"微VM中运行代码,搜索并读取网络,存储并服务文件,查询一个SQL数据库,生成文档并部署应用——通过SDK,MCP和REST API. 价格为MXN.

安装

npm install @easybits.cloud/sdk

快速启动

import { EasybitsClient } from "@easybits.cloud/sdk";

const eb = new EasybitsClient({ apiKey: "eb_sk_live_..." });

// Upload a file
const { file, putUrl } = await eb.uploadFile({
  fileName: "photo.jpg",
  contentType: "image/jpeg",
  size: 1024000,
});

// Upload bytes to the presigned URL
await fetch(putUrl, { method: "PUT", body: fileBuffer });

// Confirm upload
await eb.updateFile(file.id, { status: "DONE" });

认证

从中获取您的 API 密钥 开发者 Dashboard。 。 。 .

const eb = new EasybitsClient({ apiKey: process.env.EASYBITS_API_KEY! });

或使用自动分辨率从 ~/.easybitsrc 或 env vars : (中文(简体) )

import { createClientFromEnv } from "@easybits.cloud/sdk";
const eb = await createClientFromEnv();

方法

文件

图像

共享

网络呼号

克鲁斯

您账户中已排定的任务: 调用一个公开的 https URL( 选择以一个金库密钥作为标题) 或发送一个转机给您的车队代理 。 最多5分钟; IANA 时区( 默认) America/Mexico_City);每个计划的限制(Byte 3,Mega 20,Tera 100).

await eb.createCron({
  name: "Study reminder",
  cron: "30 8 * * *",
  action: { type: "http", url: "https://www.ghosty.studio/api/v2/me/push", method: "POST", body: { title: "Study time" }, secretName: "GHOSTY_PUSH_TOKEN" },
});

秘密(账户金库)

网站

工作空间

指定位置, 限定配额的文件容器 。 每个租户创建一个, 薄荷一个工作空间范围密钥, 而该密钥只能触摸它自己的工作空间的文件.

文档

账户

网络呼号

轻点 当事件发生时,比特将 POST 请求发送到您的 URL 。 有效载荷由HMAC SHA-256签署.

// Create a webhook
const webhook = await eb.createWebhook({
  url: "https://your-server.com/webhooks/easybits",
  events: ["file.created", "file.deleted"],
});

// Save the secret — it's only shown once
console.log(webhook.secret); // whsec_...

活动

验证签名

import { createHmac } from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
  return signature === expected;
}

// In your webhook handler:
const signature = req.headers["x-easybits-signature"];
const event = req.headers["x-easybits-event"];
const isValid = verifyWebhook(rawBody, signature, webhook.secret);

有效载荷格式

{
  "event": "file.created",
  "timestamp": "2026-02-26T12:00:00.000Z",
  "data": {
    "id": "abc123",
    "name": "photo.jpg",
    "size": 1024000,
    "contentType": "image/jpeg",
    "access": "private"
  }
}

自动暂停

Webhooks在连续5次发送失败后自动被暂停. 以 :

await eb.updateWebhook(webhookId, { status: "ACTIVE" });

实例

批量上传文件

const { items } = await eb.bulkUploadFiles([
  { fileName: "a.pdf", contentType: "application/pdf", size: 50000 },
  { fileName: "b.png", contentType: "image/png", size: 120000 },
]);

for (const { file, putUrl } of items) {
  await fetch(putUrl, { method: "PUT", body: buffers[file.name] });
  await eb.updateFile(file.id, { status: "DONE" });
}

检查账户使用情况

const stats = await eb.getUsageStats();
console.log(`${stats.storage.usedGB}/${stats.storage.maxGB} GB used`);
console.log(`${stats.counts.files} files, ${stats.counts.webhooks} webhooks`);

复制文件

const copy = await eb.duplicateFile("abc123", "photo-backup.jpg");

倾斜

每个被标注的列表返回一个信封: { items, nextCursor, hasMore } (部分) 还包括: total) (中文(简体) ). 何时 hasMore 实值 true,通过 nextCursor 恢复为 cursor 获取下一页 :

let cursor: string | undefined;
do {
  const { items, nextCursor, hasMore } = await eb.listFiles({ limit: 50, cursor });
  process(items);
  cursor = nextCursor ?? undefined;
  if (!hasMore) break;
} while (cursor);

处理错误

所有出错都有一个形状: JSON 躯体 { "error": "message" },有时与 额外字段类 code 或者说 status。 。 。 .

import { EasybitsError } from "@easybits.cloud/sdk";

try {
  await eb.getFile("nonexistent");
} catch (err) {
  if (err instanceof EasybitsError) {
    console.log(err.status); // 404
    console.log(err.body);   // '{"error":"File not found"}'
  }
}

沙盒

在孤立的鞭炮微VMs中运行代码——用持久执行代码 Jupyter 内核,管理文件,运行背景进程,并曝光端口为 公共 HTTPS URLs. (原始内容存档于2018-09-29).

import { EasybitsClient } from "@easybits.cloud/sdk";

const eb = new EasybitsClient({ apiKey: process.env.EASYBITS_API_KEY });

// Create a sandbox (waits until it's running)
const sbx = await eb.sandboxes.create({ template: "code-interpreter" });

// Persistent Python kernel — state survives between calls
await sbx.runCell("import pandas as pd; df = pd.read_csv('sales.csv')");
const out = await sbx.runCell("df.groupby('month').total.sum()");
console.log(out.stdout);

// matplotlib charts come back as image/png in results[]
const chart = await sbx.runCell("df.plot(); plt.show()");
const png = chart.results.find((r) => r.type === "image/png")?.data; // base64

// Run a server and get a public URL. Write the command as `exec <program>`:
// the shell is REPLACED by your process instead of staying as its parent, so
// signals and logs go straight to it. (Do NOT try to background something with
// nohup or & inside exec(): that call is synchronous and its shell dies with
// the response, taking the child with it. That is what execBackground is for.)
const { execId } = await sbx.execBackground("exec python3 -m http.server 3000");
const { url } = await sbx.exposePort(3000);
console.log(url); // https://sb-...-3000.sandboxes.easybits.cloud

// Poll it, list them, kill it. bgStatus returns the ACCUMULATED stdout, so
// live logs are just `st.stdout.slice(seen)` — no websockets needed.
const st = await sbx.bgStatus(execId); // { status, exitCode?, stdout, stderr }
const { processes } = await sbx.bgList(); // lost the execId? it is in here
await sbx.bgKill(execId, { graceSeconds: 2 });
// bgKill signals the whole process GROUP (SIGTERM, then SIGKILL after the
// grace), so a dev server's forked children die too instead of surviving and
// holding the port. Killing an already-finished process succeeds and reports
// alreadyExited.

// exposePort is HTTP-only (22/23/25/445/3389 are rejected). For a raw L4 port:
const fwd = await sbx.exposeRawPort(22, "tcp");
console.log(fwd.endpoint); // cname.sandboxes.easybits.cloud:49123 — dial this
// hostPort comes from a pool, differs per box and is released on destroy:
// read it back, never hardcode it. Close it with unexposeRawPort(22, "tcp").
// Only templates that declare the port work; a 403 is permanent, not transient.

// SSH: injects the key, restarts the box sshd and opens 22, in one call.
// The box sshd is fail-closed, so the key has to go in before the port opens.
const ssh = await sbx.enableSsh(["ssh-ed25519 AAAA... me@laptop"]);
console.log(ssh.command); // ssh -p 49002 root@<host of THAT box>
// Key-only, as root. disableSsh() closes the port but does NOT revoke the key.

// PREFER THE TUNNEL over that command. A high port does not survive office
// networks or corporate VPNs, and that failure reaches you as an
// unreproducible "it won't connect". The tunnel rides the same 443 as the web:
//
//   npm i -g @easybits.cloud/cli && easybits login   # or: easybits login - < key.txt
//   easybits ssh-key      # your public key; created once, never leaves the box
//
//   # ~/.ssh/config
//   Host *.ghosty
//     ProxyCommand easybits ssh-proxy %h
//     User root
//
//   ssh my-box.ghosty     # the `name` you gave it at create time
//   ssh sb_abc123.ghosty  # the id works too
//   ssh my-box.ghosty "cd /data/work && ghosty serve --acp"   # remote ACP
//
// enableSsh() is still needed once, to inject the key (the box sshd is
// fail-closed). The tunnel moves opaque bytes and does NOT authenticate: the
// SSH session authenticates end-to-end against the box's sshd, so a bug in the
// tunnel cannot let anyone in. sshTicket() mints the short-lived signed ticket
// the proxy uses — you rarely call it yourself.

// Files
await sbx.files.write("/tmp/data.json", JSON.stringify({ ok: true }));
const { content } = await sbx.files.read("/tmp/data.json");

// Lifecycle
await sbx.extend(600);   // add 10 min to the TTL
await sbx.destroy();

快照叉( 复制- 写入克隆) (F)

别动a 运行 框,然后启动 无子女 从它 - 每个独立沙盒都有自己的IP。 一次准备环境( 选项 ) 安装、项目设置、快照和叉子并列尝试 N 变体 不重复设置.

// Base box: install deps once
const base = await eb.sandboxes.create({ template: "node" });
await base.exec("npm i -g cowsay");

// Snapshot the ready state — the box keeps running
const snap = await base.snapshot("deps-ready");

// Fork into 3 children that run in parallel (each inherits the disk)
const kids = await base.fork({ count: 3 });
for (const k of kids) {
  await k.waitUntilReady();
  console.log(k.sandboxId, (await k.exec("cowsay hi")).stdout);
}

// Reuse the snapshot later, without the base box
const more = await eb.sandboxes.forkFromSnapshot(snap.snapshotId, { count: 2 });

// Catalog + cleanup
await eb.sandboxes.snapshots.list();
await eb.sandboxes.snapshots.delete(snap.snapshotId);

衍生模板( 模板- snapshot)

准备 一个 框内(npm ci种子,技能,在内容下捕捉一次 键 (key, hash),每个框 创建与该对 与生俱来 靴子绑好了 ——没有分叉,没有每个孩子的复制;主机只保留磁盘三角洲 (12-22 MB) (中文(简体) ). 测量:捕捉~0.5-1 s,取自衍生模板~0.6 s

• ~2个靴子. 这就是 @easybits.cloud/eve-sandbox 用于夜之夜 prewarm。 。 。 .

const base = await eb.sandboxes.create({ template: "node" });
await base.exec("cd /workspace && npm ci");

// Idempotent per (key, hash): a second call returns reused: true
const dt = await base.templateSnapshot({ key: "agent", hash: "3f9c" }); // { derivedId, reused, sizeBytes }

// Children never inherit the source env (secrets are scrubbed): pass their own
const child = await eb.sandboxes.create({ templateKey: "agent", templateHash: "3f9c", env: { FOO: "bar" } });

await eb.sandboxes.templateSnapshots.get({ key: "agent", hash: "3f9c" }); // 404 DerivedTemplateNotProvisioned → capture first
await eb.sandboxes.templateSnapshots.list();
await eb.sandboxes.templateSnapshots.delete(dt.derivedId);            // 409 DerivedTemplateInUse while children live

未使用30天,一个衍生模板会自删除. 如果基准模板是 重温, create 答题 409 DerivedTemplateStale:又捉来.

网络政策(每箱 Egress)

await sbx.setNetworkPolicy("deny-all");
await sbx.setNetworkPolicy({ allow: { "api.github.com": [], "registry.npmjs.org": [] } }); // no wildcards
await sbx.setNetworkPolicy("allow-all");

由主机决定IP( DNS 刷新), 坚持使用框并重新应用 简历. transform (头部注射)不支持.

睡觉/醒来(静眠)

无 suspendOnIdle,这个盒子是 已销毁 何时 timeoutSeconds (默认) 300 s)发作. 以后要谈的,你先睡吧 挂起的框是一个鞭炮快照,在~1 s 中恢复并保存磁盘和内存.

// At creation
const sbx = await eb.sandboxes.create({ template: "node", timeoutSeconds: 600, suspendOnIdle: true });

// Or on an existing box (e.g. one you created without it)
await sbx.setIdlePolicy({ suspendOnIdle: true, idleTtlSeconds: 600, hardTtlSeconds: 7 * 24 * 3600 });

await sbx.suspend();   // sleep now; TTL is paused
await sbx.resume();    // wake; the remaining lifetime is restored

模板

使用 eb.listTemplates() 用于有需要的内存的活目录。 类型 : base (运行代码), agent (已准备好的代理人), service (平台框开始于 service_start, (中文(简体) ), internal (平台创建的员工).

对于没有持续状态的一次性片段,使用 sbx.runCode(code, { lang })。 。 。 . 建筑代理人 夜 间? 吗? @easybits.cloud/eve-sandbox 转弯 这些盒子进入了夜之夜 SandboxBackend。 。 。 .

舰队特工

弹性舰队特工与麻风工人的对话(WhatsApp, WABA, 页:1 用客户端证书创建/列表/删除认证( 用户 OAuth JWT) 与 WRITE 范围); 每一个配置和信件的调用都使用每个代理 token 返回时间 create() ——坚持不懈 { id, token } 并重用符号作为 第二次辩论 一个客户端实例可以配置许多代理.

// Lifecycle — auth = client credential (pass the user JWT as apiKey)
const eb = new EasybitsClient({ apiKey: userJwt });
const { fleetAgent } = await eb.fleet.create({ name: "Tania", systemPrompt: "...", model: "claude-sonnet-5" });
const { id, token } = fleetAgent;              // persist BOTH

// Pick a non-default engine (DeepSeek/Codex/…). Some engines need a provider
// secret — set it right after with setSecret (e.g. DEEPSEEK_API_KEY).
const ds = await eb.fleet.create({ engine: "deepseek", name: "Vendedor", systemPrompt: "..." });
await eb.fleet.setSecret(ds.fleetAgent.id, ds.fleetAgent.token, { name: "DEEPSEEK_API_KEY", value: "sk-..." });
await eb.fleet.list();                          // { pools: [...] }
await eb.fleet.delete(id);

// Read config — auth = per-agent token
const caps = await eb.fleet.getCapabilities(id, token);
caps.agent.model;      // "claude-sonnet-5"
caps.agent.effort;     // "medium"
caps.skills;           // [{ id, name, enabled, ... }]

// Agent-level config
await eb.fleet.setName(id, token, "Tania");
await eb.fleet.setAgentPrompt(id, token, "New base instructions...");
await eb.fleet.setModel(id, token, "claude-opus-4-8");
await eb.fleet.setEffort(id, token, "high");           // low|medium|high|xhigh|max
await eb.fleet.toggleOwnNumber(id, token, true);
await eb.fleet.addMcp(id, token, { name: "stripe", pkg: "@stripe/mcp", requiredSecret: "STRIPE_KEY" });
await eb.fleet.toggleSkill(id, token, { skillId: "abc", on: true });

// Per-channel config (groupId; "*" = the agent's default)
await eb.fleet.setGroupPrompt(id, token, "*", "Extra per-channel instructions");
await eb.fleet.setToolGroup(id, token, "*", { buckets: ["documentos", "db", "db-write"] });
await eb.fleet.setCapLevel(id, token, "*", { cap: "denik", level: "write" });

// Messaging
const { reply } = await eb.fleet.message(id, token, { groupId: "web-123", text: "Hola" });

// WhatsApp (Baileys) connection — auth = client credential (owner), NOT the per-agent token.
// Link a PERSONAL number (never a Business/WABA number). Omit pairingPhone → QR; pass it → code.
await eb.fleet.connect(id);                          // then poll:
const { baileys } = await eb.fleet.connectionState(id);  // { status, qr?, pairingCode?, pairBlockedUntil? }
// status: qr_pending | pairing | connecting | connected | failed | disconnected. Poll ~2.5s.
const { groups } = await eb.fleet.listGroups(id);    // [{ groupId, subject, enabled, isMain }] (on-demand)
await eb.fleet.toggleGroup(id, groups[0].groupId, true);  // answer here
await eb.fleet.setMain(id, groups[0].groupId);       // admin/main channel
await eb.fleet.disconnect(id);

getCapabilities 返回完整目录 + 当前状态(已建构,容量, 桶头, bucketTools,模型,技能,每组配置. 见类型 FleetCapabilities 为了形状.

MCP 一体化

对于 AI探员,同样的沙盒作为MCP工具可用(代理调用) 它们本身——不需要代码:

npx -y @easybits.cloud/mcp

许可证

麻省理工学院