@decentnetwork/beagle

npm install @decentnetwork/beagle@0.1.132
npx beagle --help

mkdir beagle-demo && cd beagle-demo
npm init -y
npm install @decentnetwork/beagle@0.1.132
npx beagle --config-dir ./beagle-home --port 18766     # Ctrl+C to stop
# in another terminal:
curl -s http://127.0.0.1:18766/api/ping
curl -s http://127.0.0.1:18766/api/state

$ npx beagle --config-dir ./beagle-home --port 18766
[Carrier] INFO: identity KKAoGHgwvz3ng139afcE8GsoLedFAjL5pChurDkLWzn9JXWTYrgL
beagle 0.1.132 — backend: embedded (embedded peer, new identity at …/beagle-demo/beagle-home/carrier/keypair.json)
Beagle UI on http://localhost:18766

$ curl -s http://127.0.0.1:18766/api/ping
{"ok":true}

$ curl -s http://127.0.0.1:18766/api/state
{"me":{"userid":"9LFt2mAg2cnqgPmhEF284Pf6una4ioeG43exrpBek3dL","address":"KKAoGHgwvz3ng139afcE8GsoLedFAjL5pChurDkLWzn9JXWTYrgL","name":"","ip":null,"installed":false},"friends":[],"pending":[]}

// quickstart.mjs
// Open a Beagle peer host in-process (no root, no daemon) and talk to it
// with the same IPC-shaped requests the Beagle UI uses.
import { resolve } from "node:path";
import { openPeerHost, decentlanCarrierDir, ipcSocketPath, probeDaemon } from "@decentnetwork/beagle";

const configDir = resolve(process.argv[2] ?? "./beagle-demo");
const dataDir = decentlanCarrierDir(configDir);
console.log("daemon socket would be:", ipcSocketPath(dataDir));
console.log("decentlan daemon running:", await probeDaemon(dataDir));

const { host, why } = await openPeerHost({
  configDir,
  force: "embedded",
  bootstrapNodes: [
    { host: "13.58.208.50", port: 33445, pk: "89vny8MrKdDKs7Uta9RdVmspPjnRMdwMmaiEW27pZ7gh" },
    { host: "18.216.102.47", port: 33445, pk: "G5z8MqiNDFTadFUPfMdYsYtkUDbX5mNCMVHMZtsCnFeb" },
    { host: "54.193.141.205", port: 33445, pk: "7TfZWZNV8vnBxxWzJXuvKgX2QyKkLpg2oXx3LQ5tg8LW" },
  ],
  expressNodes: [{ host: "lens.beagle.chat", port: 443, pk: "ECbs4GxwGzxGerNkmqDJFibEmevu8jAXqAZtikccvD95" }],
  nickname: "docs-demo",
  autoAcceptFriends: false,
});
console.log("backend:", host.kind, "-", why, "| virtual LAN:", host.hasVirtualLan);

const diag = await host.call({ op: "diag" });
console.log("userid:", diag.ok && diag.data.identity.userid);
console.log("address:", diag.ok && diag.data.identity.address);
const friends = await host.call({ op: "friends-list" });
console.log("friends-list:", JSON.stringify(friends));
await host.stop();
console.log("stopped");
process.exit(0);

$ node quickstart.mjs
daemon socket would be: …/beagle-demo/carrier/daemon.sock
decentlan daemon running: false
[Carrier] INFO: identity GMGdcixVnhPjeJvbQGGC9F3q5k9C5NVgq6QSKD4UbYJMK3HXHNQ2
backend: embedded - embedded peer, new identity at …/beagle-demo/carrier/keypair.json | virtual LAN: false
userid: 7z3jqugUoXtcSeH6UBKiqV18613bQ3PA8pjWGuq3o6HY
address: GMGdcixVnhPjeJvbQGGC9F3q5k9C5NVgq6QSKD4UbYJMK3HXHNQ2
friends-list: {"ok":true,"data":{"friends":[]}}
stopped

type BackendKind = "daemon" | "embedded";

interface PeerHost {
  readonly kind: BackendKind;
  readonly hasVirtualLan: boolean;          // true only for the daemon backend
  call(req: IpcRequest): Promise<IpcResponse>;
  stop(): Promise<void>;
}

function openPeerHost(opts: OpenPeerHostOptions): Promise<{ host: PeerHost; why: string }>;
function defaultConfigDir(): string;                 // $AGENTNET_CONFIG_DIR or ~/.agentnet
function decentlanCarrierDir(configDir: string): string;  // carrier.dataDir from config.yaml, else <configDir>/carrier

type IpcOp =
  | "ping" | "diag"
  | "friend-request" | "friends-pending" | "friends-accept" | "friends-reject"
  | "friends-list" | "friend-remove" | "friend-set-alias" | "friends-autoaccept"
  | "set-profile" | "sign"
  | "chat-send" | "chat-history" | "chat-log-local" | "chat-mark-read" | "chat-retry"
  | "file-send" | "file-delete" | "file-cancel" | "file-retry" | "file-log-local"
  | "call-signal" | "call-poll";

interface IpcRequest { op: IpcOp; address?; hello?; userid?; text?; alias?; name?; path?; since?; limit?; … }
type IpcResponse = { ok: true; data?: Record<string, unknown> } | { ok: false; error: string };

function ipcCall(dataDir: string, req: IpcRequest, timeoutMs?: number): Promise<IpcResponse>;
function ipcSocketPath(dataDir: string, platform?: NodeJS.Platform): string; // <dataDir>/daemon.sock, or a named pipe on Windows
function probeDaemon(dataDir: string, timeoutMs?: number): Promise<boolean>; // connects, so it answers on every platform
function daemonSocketMayExist(dataDir: string): boolean;                     // sync hint only

function startBeagleServer(opts: BeagleServerOptions): { stop: () => void };

beagle [options]
  --port <n>         HTTP port (default 8766, or $BEAGLE_PORT)
  --host <addr>      bind address (default 127.0.0.1)
  --config-dir <p>   identity/config dir (default ~/.agentnet, or $AGENTNET_CONFIG_DIR)
  --dora-dir <p>     dora roster dir, if this machine runs a dora
  --bridge <wss>     bridge whose roster to show (default wss://bridge.beagle.chat/relay-ws)
  --backend <k>      force 'daemon' or 'embedded' (default: auto)
  --wait-daemon <s>  with --backend daemon, wait this long for it (default 60)
  -h, --help