Skip to main content

Node SDK

Vibecontrols' primary scripting interface is the vibecontrols CLI (@vibecontrols/cli) — built on the internal CLI core which wraps the GraphQL gateway.

For programmatic Node access:

Option 1: Shell out to the CLI​

import {execFile} from "node:child_process";
import {promisify} from "node:util";
const exec = promisify(execFile);

const {stdout} = await exec("vibecontrols", ["vibes", "list", "--json"]);
const vibes = JSON.parse(stdout);

Most CLI commands support --json for structured output.

Option 2: Call the GraphQL API directly​

The Vibecontrols backend is a GraphQL surface inside Burdenoff Workspaces. Use the platform's Node SDK or any GraphQL client:

import {GraphQLClient} from "graphql-request";

const client = new GraphQLClient(
  "https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
  {
    headers: {
      authorization: `Bearer ${process.env.BURDENOFF_TOKEN}`,
      "x-workspace-id": process.env.WORKSPACE_ID,
    },
  }
);

const data = await client.request(`
  query { myAgents { id name isActive } }
`);

See GraphQL API for the schema reference.

Option 3: Talk to the agent's REST API​

If you're on the same machine as the agent (typical for plugins or scripts), use the local REST API directly. See REST API.

import {readFile} from "node:fs/promises";
import {homedir} from "node:os";
import {join} from "node:path";

const configPath = join(homedir(), ".boff/vibecontrols/agents/<id>/config.json");
const {agentApiKey} = JSON.parse(await readFile(configPath, "utf8"));

const res = await fetch("http://localhost:3005/api/profiles/default/agent/identity", {
  headers: {"x-agent-api-key": agentApiKey},
});
const identity = await res.json();

Next steps​