@boxcompute/cli 0.1.1

package/README.md

@@ -0,0 +1,46 @@
+# BoxCompute CLI
+
+Connect Claude Code, Codex, Amp, OpenCode, and other local coding agents to
+isolated BoxCompute sandboxes.
+
+## Install
+
+```sh
+npm install --global @boxcompute/cli
+bxc login
+```
+
+`bxc login` opens BoxCompute in your browser. After you approve the device, the
+CLI stores its credential outside the project under `~/.config/boxcompute` with
+restrictive file permissions. The credential is never included in the agent
+skill.
+
+For a self-hosted BoxCompute deployment, provide its web origin:
+
+```sh
+bxc login --url https://boxcompute.example.com
+```
+
+## Install the agent skill
+
+```sh
+bxc skill detect
+bxc skill install
+```
+
+The installer checks known configuration directories and executables for
+compatible coding harnesses. It does not recursively scan your home directory.
+Use `bxc skill install all` to target every supported harness, or name one or
+more explicitly. Run `bxc skill remove --yes` to uninstall matching copies.
+
+## Use sandboxes
+
+```sh
+bxc doctor
+bxc sandboxes
+bxc sandbox start WORKSPACE_ID
+bxc sandbox exec WORKSPACE_ID -- python -m pytest
+```
+
+Run `bxc` or `bxc --help` for the complete command reference. The previous
+`bcompute` executable remains available as a compatibility alias.

package/dist/cli.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { type Connection } from "./config.js";
+import { detectHarnesses, installSkill, readSkill, removeSkill } from "./skill.js";
+type Io = {
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+};
+export type CliDependencies = {
+    env?: NodeJS.ProcessEnv;
+    io?: Io;
+    fetch?: typeof fetch;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    openBrowser?: (url: string) => void;
+    loadConnection?: (env: NodeJS.ProcessEnv) => Promise<Connection>;
+    loadSavedUrl?: (env: NodeJS.ProcessEnv) => Promise<string | null>;
+    saveConnection?: (url: string, token: string, env: NodeJS.ProcessEnv) => Promise<void>;
+    clearConnection?: (env: NodeJS.ProcessEnv) => Promise<void>;
+    detectHarnesses?: typeof detectHarnesses;
+    installSkill?: typeof installSkill;
+    removeSkill?: typeof removeSkill;
+    readSkill?: typeof readSkill;
+};
+export declare function runCli(argv: string[], supplied?: CliDependencies): Promise<number>;
+export declare function formatCliError(error: unknown): string;
+export {};

package/dist/cli.js

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { hostname, platform } from "node:os";
+import { fileURLToPath } from "node:url";
+import { BoxComputeClient, BoxComputeHttpError, publicRequest, } from "./client.js";
+import { clearConnection, loadConnection, loadSavedUrl, saveConnection, } from "./config.js";
+import { HARNESS_IDS, detectHarnesses, installSkill, readSkill, removeSkill, } from "./skill.js";
+const DEFAULT_URL = "https://app.boxcompute.ai";
+const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const rootHelp = `BoxCompute CLI
+
+Usage: bxc [options] [command]
+
+Commands:
+
+  version                         Print the version number and exit
+  login                           Log in through BoxCompute in your browser
+  logout                          Revoke and remove the saved CLI credential
+  auth                            [alias: login] Authentication commands
+    logout                        Revoke and remove the saved CLI credential
+  doctor                          Verify the saved connection
+  sandboxes                       [aliases: list, ls] List workspaces and sandbox state
+  sandbox                         Manage isolated BoxCompute sandboxes
+    start                         Start or resume a workspace sandbox
+    status                        Inspect one sandbox
+    exec                          Execute a program inside a sandbox
+    delete                        [alias: rm] Destroy the runtime; the workspace remains
+  skill                           [alias: skills] Manage coding-harness skills
+    detect                        Detect compatible coding harnesses
+    list                          [alias: ls] List detected or installed harnesses
+    install                       [alias: add] Install the BoxCompute skill
+    remove                        [aliases: rm, uninstall] Remove the BoxCompute skill
+    info                          [alias: print] Print the packaged skill
+
+Options:
+
+  -V, --version                   Print the version number and exit
+  --json                          Emit machine-readable JSON
+  -h, --help                      Display help for a command
+
+Login options:
+
+  --url URL                       BoxCompute web URL (default: https://app.boxcompute.ai)
+  --no-open                       Print the approval URL without opening a browser
+
+Examples:
+
+  $ bxc login
+  $ bxc skill detect
+  $ bxc skill install
+  $ bxc sandbox exec WORKSPACE_ID -- python -m pytest
+
+Compatibility:
+
+  The previous bcompute command remains available as an alias.
+`;
+const sandboxHelp = `Manage isolated BoxCompute sandboxes
+
+Usage: bxc sandbox <command> [options]
+
+Commands:
+
+  start WORKSPACE_ID              Start or resume a workspace sandbox
+  status SANDBOX_ID               Inspect one sandbox
+  exec SANDBOX_ID [options] -- PROGRAM [ARG...]
+                                  Execute a program inside a sandbox
+  delete SANDBOX_ID --yes         [alias: rm] Destroy the runtime; keep the workspace
+
+Exec options:
+
+  --cwd PATH                      Working directory under /workspace
+  --env KEY=VALUE                 Set an environment variable; repeatable
+  --timeout SECONDS               Command timeout
+  --max-output-bytes BYTES        Maximum captured output
+`;
+const skillHelp = `Manage coding-harness skills
+
+Usage: bxc skill <command> [options]
+
+Commands:
+
+  detect                          Detect compatible coding harnesses
+  list                            [alias: ls] List detected or installed harnesses
+  install [auto|all|HARNESS...]   [alias: add] Install to detected harnesses by default
+  remove [auto|all|HARNESS...]    [aliases: rm, uninstall] Remove from detected harnesses
+  info                            [alias: print] Print the packaged BoxCompute skill
+
+Install options:
+
+  --force                         Replace a locally modified skill
+
+Remove options:
+
+  --yes                           Confirm removal
+  --force                         Remove a locally modified skill
+
+Supported harnesses:
+  claude, codex, amp, opencode, cursor, gemini, copilot, cline, roo,
+  goose, pi, windsurf, and the shared agents directory
+`;
+class UsageError extends Error {
+    constructor(message) { super(message); this.name = "UsageError"; }
+}
+function browser(url) {
+    const system = platform();
+    const command = system === "darwin" ? "open" : system === "win32" ? "cmd" : "xdg-open";
+    const args = system === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => undefined);
+    child.unref();
+}
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const write = (stream, value) => { stream.write(value); };
+const emit = (io, json, value, human) => {
+    write(io.stdout, json ? `${JSON.stringify(value)}\n` : human);
+};
+function option(tokens, name) {
+    const index = tokens.indexOf(`--${name}`);
+    if (index < 0)
+        return undefined;
+    const value = tokens[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new UsageError(`--${name} requires a value`);
+    tokens.splice(index, 2);
+    return value;
+}
+function flag(tokens, name) {
+    const index = tokens.indexOf(`--${name}`);
+    if (index < 0)
+        return false;
+    tokens.splice(index, 1);
+    return true;
+}
+function anyFlag(tokens, ...names) {
+    const index = tokens.findIndex((token) => names.includes(token));
+    if (index < 0)
+        return false;
+    tokens.splice(index, 1);
+    return true;
+}
+function positive(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new UsageError(`${name} must be a positive integer`);
+    return parsed;
+}
+function environment(tokens) {
+    const values = [];
+    for (;;) {
+        const index = tokens.indexOf("--env");
+        if (index < 0)
+            break;
+        const value = tokens[index + 1];
+        if (!value)
+            throw new UsageError("--env requires KEY=VALUE");
+        values.push(value);
+        tokens.splice(index, 2);
+    }
+    if (!values.length)
+        return undefined;
+    return Object.fromEntries(values.map((value) => {
+        const at = value.indexOf("=");
+        if (at < 1)
+            throw new UsageError("--env requires KEY=VALUE");
+        return [value.slice(0, at), value.slice(at + 1)];
+    }));
+}
+async function authenticate(args, dependencies) {
+    const url = option(args, "url") ?? await dependencies.loadSavedUrl(dependencies.env) ?? DEFAULT_URL;
+    const noOpen = flag(args, "no-open");
+    if (args.length)
+        throw new UsageError(`Unexpected auth argument: ${args[0]}`);
+    let started;
+    try {
+        started = await publicRequest(url, "/api/cli-auth/device", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ clientName: `${hostname()} (${platform()})` }),
+        }, dependencies.fetch);
+    }
+    catch (error) {
+        if (error instanceof BoxComputeHttpError && [401, 404, 405].includes(error.status)) {
+            throw new Error(`Browser login is not available at ${url} (HTTP ${error.status}). ` +
+                "The BoxCompute server must be updated to support CLI authentication. " +
+                "For a local or self-hosted server, run `bxc login --url WEB_URL`.");
+        }
+        throw error;
+    }
+    const verificationUrl = new URL(started.verificationUriComplete);
+    if (verificationUrl.origin !== new URL(url).origin ||
+        !started.deviceCode.startsWith("bcd_") ||
+        !/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(started.userCode) ||
+        !Number.isFinite(started.expiresIn) ||
+        started.expiresIn <= 0 ||
+        !Number.isFinite(started.interval) ||
+        started.interval <= 0) {
+        throw new Error("BoxCompute returned an invalid browser authentication response");
+    }
+    write(dependencies.io.stderr, `\nOpen this URL to authenticate:\n${verificationUrl.href}\n\nCode: ${started.userCode}\n\n`);
+    if (!noOpen)
+        dependencies.openBrowser(verificationUrl.href);
+    write(dependencies.io.stderr, "Waiting for browser approval…\n");
+    const deadline = dependencies.now() + started.expiresIn * 1000;
+    while (dependencies.now() < deadline) {
+        await dependencies.sleep(Math.max(1, started.interval) * 1000);
+        try {
+            const result = await publicRequest(url, "/api/cli-auth/token", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ deviceCode: started.deviceCode }),
+            }, dependencies.fetch);
+            await dependencies.saveConnection(url, result.token, dependencies.env);
+            emit(dependencies.io, dependencies.json, { authenticated: true, url }, `Authenticated with ${url}.\nNext: bxc skill install\n`);
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof BoxComputeHttpError && error.status === 428 && error.message === "authorization_pending")
+                continue;
+            if (error instanceof BoxComputeHttpError && error.status === 410)
+                throw new Error("Browser authentication expired. Run `bxc auth` again.");
+            throw error;
+        }
+    }
+    throw new Error("Browser authentication expired. Run `bxc auth` again.");
+}
+function sandboxLine(sandbox) {
+    return `${sandbox.id}\t${sandbox.state}\t${sandbox.name}\n`;
+}
+function executionOutput(io, json, sandboxId, result) {
+    if (json)
+        emit(io, true, { sandboxId, ...result }, "");
+    else {
+        write(io.stdout, result.stdout);
+        write(io.stderr, result.stderr);
+        write(io.stderr, `sandbox=${sandboxId} exitCode=${result.exitCode ?? "null"} timedOut=${result.timedOut}\n`);
+    }
+    return result.exitCode ?? 1;
+}
+export async function runCli(argv, supplied = {}) {
+    const env = supplied.env ?? process.env;
+    const io = supplied.io ?? { stdout: process.stdout, stderr: process.stderr };
+    const fetchImpl = supplied.fetch ?? fetch;
+    const now = supplied.now ?? Date.now;
+    const sleep = supplied.sleep ?? delay;
+    const openBrowser = supplied.openBrowser ?? browser;
+    const load = supplied.loadConnection ?? loadConnection;
+    const savedUrl = supplied.loadSavedUrl ?? loadSavedUrl;
+    const save = supplied.saveConnection ?? saveConnection;
+    const clear = supplied.clearConnection ?? clearConnection;
+    const detect = supplied.detectHarnesses ?? detectHarnesses;
+    const install = supplied.installSkill ?? installSkill;
+    const remove = supplied.removeSkill ?? removeSkill;
+    const skillText = supplied.readSkill ?? readSkill;
+    const args = [...argv];
+    const json = flag(args, "json");
+    const versionRequested = args[0] === "version" || anyFlag(args, "--version", "-V", "-v");
+    if (versionRequested) {
+        emit(io, json, { version: CLI_VERSION }, `${CLI_VERSION}\n`);
+        return 0;
+    }
+    const helpRequested = anyFlag(args, "--help", "-h");
+    if (!args.length || args[0] === "help" || helpRequested) {
+        const helpTarget = args[0] === "help" ? args[1] : args[0];
+        write(io.stdout, helpFor(helpTarget));
+        return 0;
+    }
+    let command = args.shift();
+    if (command === "login")
+        command = "auth";
+    if (command === "skills")
+        command = "skill";
+    if (command === "list" || command === "ls")
+        command = "sandboxes";
+    if (command === "logout") {
+        if (args.length)
+            throw new UsageError("logout takes no options");
+        const connection = await load(env);
+        await new BoxComputeClient(connection, fetchImpl).logout();
+        await clear(env);
+        emit(io, json, { authenticated: false }, "BoxCompute CLI credential revoked and removed.\n");
+        return 0;
+    }
+    if (command === "auth") {
+        if (args[0] === "login")
+            args.shift();
+        if (args[0] === "logout") {
+            args.shift();
+            if (args.length)
+                throw new UsageError("auth logout takes no options");
+            const connection = await load(env);
+            await new BoxComputeClient(connection, fetchImpl).logout();
+            await clear(env);
+            emit(io, json, { authenticated: false }, "BoxCompute CLI credential revoked and removed.\n");
+            return 0;
+        }
+        return authenticate(args, { env, io, json, fetch: fetchImpl, now, sleep, openBrowser, loadSavedUrl: savedUrl, saveConnection: save });
+    }
+    if (command === "skill") {
+        let action = args.shift();
+        if (!action) {
+            write(io.stdout, skillHelp);
+            return 0;
+        }
+        if (action === "ls")
+            action = "list";
+        if (action === "add")
+            action = "install";
+        if (action === "rm" || action === "uninstall")
+            action = "remove";
+        if (action === "print")
+            action = "info";
+        if (action === "detect") {
+            if (args.length)
+                throw new UsageError("skill detect takes no options");
+            const harnesses = (await detect(env)).filter((item) => item.detected);
+            emit(io, json, { harnesses }, harnesses.length
+                ? `Detected coding harnesses:\n${harnesses.map(harnessLine).join("")}\nRun \`bxc skill install\` to install automatically.\n`
+                : "No supported coding harnesses detected. You can name one explicitly or use `bxc skill install all`.\n");
+            return 0;
+        }
+        if (action === "list") {
+            if (args.length)
+                throw new UsageError("skill list takes no options");
+            const harnesses = (await detect(env)).filter((item) => item.detected || item.installed);
+            emit(io, json, { harnesses }, harnesses.length
+                ? `Coding harness skills:\n${harnesses.map(harnessLine).join("")}`
+                : "No supported coding harnesses detected and no BoxCompute skills installed.\n");
+            return 0;
+        }
+        if (action === "info") {
+            if (args.length)
+                throw new UsageError("skill info takes no options");
+            write(io.stdout, await skillText());
+            return 0;
+        }
+        if (action !== "install" && action !== "remove") {
+            throw new UsageError("skill requires `detect`, `list`, `install`, `remove`, or `info`");
+        }
+        const force = flag(args, "force");
+        const confirmed = flag(args, "yes");
+        const targets = (args.length ? args : ["auto"]);
+        const supported = new Set([...HARNESS_IDS, "auto", "all", "both"]);
+        const invalid = targets.find((target) => !supported.has(target));
+        if (invalid)
+            throw new UsageError(`Unknown coding harness: ${invalid}`);
+        if (action === "remove") {
+            if (!confirmed)
+                throw new UsageError("skill remove requires --yes");
+            const removed = await remove(targets, { force, env });
+            emit(io, json, { removed }, `${removed.map((item) => `${removalStatus(item.status)} for ${item.agents.join(", ")}: ${item.path}`).join("\n")}\n`);
+            return 0;
+        }
+        if (confirmed)
+            throw new UsageError("--yes is only valid with skill remove");
+        const installed = await install(targets, { force, env });
+        emit(io, json, { installed }, `${installed.map((item) => `${skillStatus(item.status)} for ${item.agents.join(", ")}: ${item.path}`).join("\n")}\n`);
+        return 0;
+    }
+    if (command === "sandbox" && !args.length) {
+        write(io.stdout, sandboxHelp);
+        return 0;
+    }
+    const connection = await load(env);
+    const client = new BoxComputeClient(connection, fetchImpl);
+    if (command === "doctor") {
+        const sandboxes = await client.list();
+        emit(io, json, { connected: true, url: connection.url, sandboxes: sandboxes.length }, `Connected to ${connection.url} · ${sandboxes.length} workspace${sandboxes.length === 1 ? "" : "s"}\n`);
+        return 0;
+    }
+    if (command === "sandboxes") {
+        if (args.length)
+            throw new UsageError("sandboxes takes no options");
+        const sandboxes = await client.list();
+        emit(io, json, { sandboxes }, sandboxes.length ? sandboxes.map(sandboxLine).join("") : "No workspaces found. Create one in BoxCompute first.\n");
+        return 0;
+    }
+    if (command !== "sandbox")
+        throw new UsageError(`Unknown command: ${command}`);
+    let action = args.shift();
+    if (action === "rm")
+        action = "delete";
+    const id = args.shift();
+    if (!action || !id)
+        throw new UsageError("sandbox requires an action and sandbox ID");
+    if (action === "start") {
+        if (args.length)
+            throw new UsageError("sandbox start takes one workspace ID");
+        const sandbox = await client.start(id);
+        emit(io, json, { sandbox }, sandboxLine(sandbox));
+        return 0;
+    }
+    if (action === "status") {
+        if (args.length)
+            throw new UsageError("sandbox status takes one sandbox ID");
+        const sandbox = await client.inspect(id);
+        emit(io, json, { sandbox }, sandboxLine(sandbox));
+        return 0;
+    }
+    if (action === "delete") {
+        if (!flag(args, "yes") || args.length)
+            throw new UsageError("sandbox delete requires SANDBOX_ID --yes");
+        await client.delete(id);
+        emit(io, json, { sandboxId: id, deleted: true }, `Destroyed sandbox runtime ${id}; its workspace remains.\n`);
+        return 0;
+    }
+    if (action === "exec") {
+        const separator = args.indexOf("--");
+        if (separator < 0 || separator === args.length - 1)
+            throw new UsageError("sandbox exec requires a program after --");
+        const options = args.splice(0, separator);
+        args.shift();
+        const cwd = option(options, "cwd");
+        const timeoutSeconds = positive(option(options, "timeout"), "--timeout");
+        const maxOutputBytes = positive(option(options, "max-output-bytes"), "--max-output-bytes");
+        const envInput = environment(options);
+        if (options.length)
+            throw new UsageError(`Unknown sandbox exec option: ${options[0]}`);
+        return executionOutput(io, json, id, await client.execute(id, { argv: args, cwd, timeoutSeconds, maxOutputBytes, env: envInput }));
+    }
+    throw new UsageError(`Unknown sandbox action: ${action}`);
+}
+function harnessLine(harness) {
+    const status = harness.installed ? "installed" : "detected";
+    return `  ${harness.label}\t${status}\t${harness.path}\n`;
+}
+function skillStatus(status) {
+    if (status === "updated")
+        return "Updated";
+    if (status === "unchanged")
+        return "Already installed";
+    return "Installed";
+}
+function removalStatus(status) {
+    return status === "removed" ? "Removed" : "Not installed";
+}
+function helpFor(command) {
+    if (command === "sandbox")
+        return sandboxHelp;
+    if (command === "skill" || command === "skills")
+        return skillHelp;
+    return rootHelp;
+}
+export function formatCliError(error) {
+    if (error instanceof BoxComputeHttpError)
+        return `${error.message} (HTTP ${error.status})`;
+    return error instanceof Error ? error.message : String(error);
+}
+async function main() {
+    try {
+        process.exitCode = await runCli(process.argv.slice(2));
+    }
+    catch (error) {
+        write(process.stderr, `${error instanceof UsageError ? "Usage" : "Error"}: ${formatCliError(error)}\n`);
+        process.exitCode = error instanceof UsageError ? 2 : 1;
+    }
+}
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        // npm exposes package binaries through a symlink. Comparing the raw argv
+        // path with import.meta.url makes the installed CLI look like a library and
+        // silently skips main(), so resolve both sides before comparing them.
+        return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule())
+    await main();

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+import type { Connection } from "./config.js";
+export type Sandbox = {
+    id: string;
+    workspaceId: string;
+    name: string;
+    state: "not-created" | "cold" | "running";
+    runtimeId: string | null;
+    image: string | null;
+    createdAt: number;
+    lastUsedAt: number | null;
+};
+export type Execution = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    wallTimeSeconds: number;
+};
+export declare class BoxComputeHttpError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export declare function publicRequest<T>(url: string, pathname: string, init: RequestInit, fetchImpl?: typeof fetch): Promise<T>;
+export declare class BoxComputeClient {
+    private readonly connection;
+    private readonly fetchImpl;
+    constructor(connection: Connection, fetchImpl?: typeof fetch);
+    private request;
+    list(): Promise<Sandbox[]>;
+    logout(): Promise<void>;
+    inspect(id: string): Promise<Sandbox>;
+    start(workspaceId: string): Promise<Sandbox>;
+    execute(id: string, input: {
+        argv: string[];
+        cwd?: string;
+        timeoutSeconds?: number;
+        maxOutputBytes?: number;
+        env?: Record<string, string>;
+    }): Promise<Execution>;
+    delete(id: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,59 @@
+export class BoxComputeHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "BoxComputeHttpError";
+    }
+}
+async function responseError(response) {
+    const body = await response.json().catch(() => ({}));
+    return new BoxComputeHttpError(response.status, body.error ?? `BoxCompute returned HTTP ${response.status}`, body.code);
+}
+export async function publicRequest(url, pathname, init, fetchImpl = fetch) {
+    const response = await fetchImpl(new URL(pathname, `${url}/`), init);
+    if (!response.ok)
+        throw await responseError(response);
+    return response.status === 204 ? undefined : await response.json();
+}
+export class BoxComputeClient {
+    connection;
+    fetchImpl;
+    constructor(connection, fetchImpl = fetch) {
+        this.connection = connection;
+        this.fetchImpl = fetchImpl;
+    }
+    request(pathname, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set("authorization", `Bearer ${this.connection.token}`);
+        return publicRequest(this.connection.url, pathname, { ...init, headers }, this.fetchImpl);
+    }
+    async list() {
+        return (await this.request("/api/v1/sandboxes")).sandboxes;
+    }
+    async logout() {
+        await this.request("/api/v1/auth", { method: "DELETE" });
+    }
+    async inspect(id) {
+        return (await this.request(`/api/v1/sandboxes/${encodeURIComponent(id)}`)).sandbox;
+    }
+    async start(workspaceId) {
+        return (await this.request("/api/v1/sandboxes", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ workspaceId }),
+        })).sandbox;
+    }
+    async execute(id, input) {
+        return (await this.request(`/api/v1/sandboxes/${encodeURIComponent(id)}/execute`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(input),
+        })).result;
+    }
+    async delete(id) {
+        await this.request(`/api/v1/sandboxes/${encodeURIComponent(id)}`, { method: "DELETE" });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export type Connection = {
+    url: string;
+    token: string;
+    tokenFile: string;
+};
+export declare function normalizeBaseUrl(value: string): string;
+export declare function connectionPaths(env?: NodeJS.ProcessEnv): {
+    directory: string;
+    configFile: string;
+    tokenFile: string;
+};
+export declare function loadConnection(env?: NodeJS.ProcessEnv): Promise<Connection>;
+export declare function loadSavedUrl(env?: NodeJS.ProcessEnv): Promise<string | null>;
+export declare function saveConnection(url: string, token: string, env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function clearConnection(env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/config.js

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+export function normalizeBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("BoxCompute URL must be an absolute http or https URL");
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+        throw new Error("BoxCompute URL must be an http or https origin without credentials");
+    }
+    if ((url.pathname !== "/" && url.pathname !== "") || url.search || url.hash) {
+        throw new Error("BoxCompute URL must be an origin without a path, query, or fragment");
+    }
+    return url.origin;
+}
+export function connectionPaths(env = process.env) {
+    const directory = env.BOXCOMPUTE_CONFIG_DIR
+        ? path.resolve(env.BOXCOMPUTE_CONFIG_DIR)
+        : path.join(env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : homedir(), "boxcompute");
+    return {
+        directory,
+        configFile: path.join(directory, "config.json"),
+        tokenFile: path.join(directory, "credential"),
+    };
+}
+async function secureFile(file) {
+    const mode = (await stat(file)).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`${file} must not be readable by group or other users (run chmod 600)`);
+    }
+}
+export async function loadConnection(env = process.env) {
+    const paths = connectionPaths(env);
+    let url = env.BOXCOMPUTE_URL;
+    let tokenFile = env.BOXCOMPUTE_TOKEN_FILE;
+    if (!url || !tokenFile) {
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(paths.configFile, "utf8"));
+        }
+        catch {
+            throw new Error("Not authenticated. Run `bxc auth` first.");
+        }
+        url ??= typeof parsed.url === "string" ? parsed.url : undefined;
+        tokenFile ??= typeof parsed.tokenFile === "string" ? parsed.tokenFile : undefined;
+    }
+    if (!url || !tokenFile)
+        throw new Error("Not authenticated. Run `bxc auth` first.");
+    const resolvedTokenFile = path.resolve(tokenFile);
+    await secureFile(resolvedTokenFile);
+    const token = (await readFile(resolvedTokenFile, "utf8")).trim();
+    if (!token.startsWith("bc_live_"))
+        throw new Error("The saved BoxCompute credential is invalid. Run `bxc auth` again.");
+    return { url: normalizeBaseUrl(url), token, tokenFile: resolvedTokenFile };
+}
+export async function loadSavedUrl(env = process.env) {
+    if (env.BOXCOMPUTE_URL)
+        return normalizeBaseUrl(env.BOXCOMPUTE_URL);
+    try {
+        const parsed = JSON.parse(await readFile(connectionPaths(env).configFile, "utf8"));
+        return typeof parsed.url === "string" ? normalizeBaseUrl(parsed.url) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveConnection(url, token, env = process.env) {
+    if (!token.startsWith("bc_live_"))
+        throw new Error("BoxCompute returned an invalid credential");
+    const paths = connectionPaths(env);
+    await mkdir(paths.directory, { recursive: true, mode: 0o700 });
+    await chmod(paths.directory, 0o700);
+    const suffix = randomUUID();
+    const tokenTemp = `${paths.tokenFile}.${suffix}.tmp`;
+    const configTemp = `${paths.configFile}.${suffix}.tmp`;
+    try {
+        await writeFile(tokenTemp, `${token}\n`, { mode: 0o600, flag: "wx" });
+        await writeFile(configTemp, `${JSON.stringify({ url: normalizeBaseUrl(url), tokenFile: paths.tokenFile }, null, 2)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(tokenTemp, paths.tokenFile);
+        await chmod(paths.tokenFile, 0o600);
+        await rename(configTemp, paths.configFile);
+        await chmod(paths.configFile, 0o600);
+    }
+    finally {
+        await rm(tokenTemp, { force: true }).catch(() => undefined);
+        await rm(configTemp, { force: true }).catch(() => undefined);
+    }
+}
+export async function clearConnection(env = process.env) {
+    const paths = connectionPaths(env);
+    await rm(paths.tokenFile, { force: true });
+    await rm(paths.configFile, { force: true });
+}

package/dist/skill.d.ts

@@ -0,0 +1,31 @@
+export declare const HARNESS_IDS: readonly ["claude", "codex", "amp", "opencode", "cursor", "gemini", "copilot", "cline", "roo", "goose", "pi", "windsurf", "agents"];
+export type HarnessId = (typeof HARNESS_IDS)[number];
+export type AgentTarget = HarnessId | "auto" | "all" | "both";
+export type HarnessDetection = {
+    id: HarnessId;
+    label: string;
+    detected: boolean;
+    signals: string[];
+    path: string;
+    installed: boolean;
+};
+export type SkillInstallation = {
+    agents: string[];
+    path: string;
+};
+export type SkillInstallationResult = SkillInstallation & {
+    status: "installed" | "updated" | "unchanged";
+};
+export type SkillRemovalResult = SkillInstallation & {
+    status: "removed" | "missing";
+};
+export declare function detectHarnesses(env?: NodeJS.ProcessEnv): Promise<HarnessDetection[]>;
+export declare function installSkill(requested?: AgentTarget | AgentTarget[], options?: {
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Promise<SkillInstallationResult[]>;
+export declare function removeSkill(requested?: AgentTarget | AgentTarget[], options?: {
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Promise<SkillRemovalResult[]>;
+export declare function readSkill(): Promise<string>;

package/dist/skill.js

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, cp, mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const HARNESS_IDS = [
+    "claude",
+    "codex",
+    "amp",
+    "opencode",
+    "cursor",
+    "gemini",
+    "copilot",
+    "cline",
+    "roo",
+    "goose",
+    "pi",
+    "windsurf",
+    "agents",
+];
+const sourceSkill = fileURLToPath(new URL("../skills/boxcompute-sandbox", import.meta.url));
+function locations(env) {
+    const home = env.HOME || homedir();
+    return {
+        home,
+        config: env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(home, ".config"),
+        codex: env.CODEX_HOME ? path.resolve(env.CODEX_HOME) : path.join(home, ".codex"),
+    };
+}
+const sharedRoot = ({ home }) => path.join(home, ".agents", "skills");
+const definitions = [
+    { id: "claude", label: "Claude Code", commands: ["claude"], markers: ({ home }) => [path.join(home, ".claude")], skillRoot: ({ home }) => path.join(home, ".claude", "skills") },
+    { id: "codex", label: "Codex", commands: ["codex"], markers: ({ codex }) => [codex], skillRoot: ({ codex }) => path.join(codex, "skills") },
+    { id: "amp", label: "Amp", commands: ["amp"], markers: ({ config }) => [path.join(config, "amp")], skillRoot: ({ home }) => path.join(home, ".claude", "skills") },
+    { id: "opencode", label: "OpenCode", commands: ["opencode"], markers: ({ config, home }) => [path.join(config, "opencode"), path.join(home, ".opencode")], skillRoot: ({ config }) => path.join(config, "opencode", "skills") },
+    { id: "cursor", label: "Cursor", commands: ["cursor", "cursor-agent"], markers: ({ home }) => [path.join(home, ".cursor")], skillRoot: ({ home }) => path.join(home, ".cursor", "skills") },
+    { id: "gemini", label: "Gemini CLI", commands: ["gemini"], markers: ({ home }) => [path.join(home, ".gemini")], skillRoot: ({ home }) => path.join(home, ".gemini", "skills") },
+    { id: "copilot", label: "GitHub Copilot", commands: ["copilot"], markers: ({ home }) => [path.join(home, ".copilot")], skillRoot: ({ home }) => path.join(home, ".copilot", "skills") },
+    { id: "cline", label: "Cline", commands: ["cline"], markers: ({ home }) => [path.join(home, ".cline")], skillRoot: ({ home }) => path.join(home, ".cline", "skills") },
+    { id: "roo", label: "Roo Code", commands: ["roo"], markers: ({ home }) => [path.join(home, ".roo")], skillRoot: ({ home }) => path.join(home, ".roo", "skills") },
+    { id: "goose", label: "goose", commands: ["goose"], markers: ({ config }) => [path.join(config, "goose")], skillRoot: sharedRoot },
+    { id: "pi", label: "Pi", commands: ["pi"], markers: ({ home }) => [path.join(home, ".pi")], skillRoot: ({ home }) => path.join(home, ".pi", "agent", "skills") },
+    { id: "windsurf", label: "Windsurf", commands: ["windsurf"], markers: ({ home }) => [path.join(home, ".codeium", "windsurf")], skillRoot: sharedRoot },
+    { id: "agents", label: "Agent Skills compatible harnesses", commands: [], markers: ({ home }) => [path.join(home, ".agents")], skillRoot: sharedRoot },
+];
+async function exists(candidate) {
+    return stat(candidate).then(() => true, () => false);
+}
+async function directoryDigest(directory) {
+    const digest = createHash("sha256");
+    const walk = async (current, prefix = "") => {
+        const entries = await readdir(current, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const relative = path.posix.join(prefix, entry.name);
+            const absolute = path.join(current, entry.name);
+            if (entry.isDirectory())
+                await walk(absolute, relative);
+            else if (entry.isFile()) {
+                digest.update(relative);
+                digest.update("\0");
+                digest.update(await readFile(absolute));
+                digest.update("\0");
+            }
+            else {
+                throw new Error(`Unsupported skill entry: ${relative}`);
+            }
+        }
+    };
+    await walk(directory);
+    return digest.digest("hex");
+}
+async function matchesPackagedSkill(candidate) {
+    try {
+        return await directoryDigest(candidate) === await directoryDigest(sourceSkill);
+    }
+    catch {
+        return false;
+    }
+}
+async function commandExists(command, env) {
+    if (!env.PATH)
+        return false;
+    const extensions = process.platform === "win32"
+        ? (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";")
+        : [""];
+    for (const directory of env.PATH.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const executable = path.join(directory, `${command}${extension}`);
+            if (await access(executable, constants.X_OK).then(() => true, () => false))
+                return true;
+        }
+    }
+    return false;
+}
+export async function detectHarnesses(env = process.env) {
+    const resolved = locations(env);
+    return Promise.all(definitions.map(async (definition) => {
+        const signals = [];
+        const skillPath = path.join(definition.skillRoot(resolved), "boxcompute-sandbox");
+        for (const marker of definition.markers(resolved)) {
+            if (await exists(marker))
+                signals.push(marker);
+        }
+        for (const command of definition.commands) {
+            if (await commandExists(command, env))
+                signals.push(`command:${command}`);
+        }
+        return {
+            id: definition.id,
+            label: definition.label,
+            detected: signals.length > 0,
+            signals,
+            path: skillPath,
+            installed: await exists(skillPath),
+        };
+    }));
+}
+function expandedTargets(targets) {
+    if (targets.includes("auto")) {
+        if (targets.length !== 1)
+            throw new Error("auto cannot be combined with other harnesses");
+        return "auto";
+    }
+    if (targets.includes("all")) {
+        if (targets.length !== 1)
+            throw new Error("all cannot be combined with other harnesses");
+        return "all";
+    }
+    return [...new Set(targets.flatMap((target) => target === "both" ? ["claude", "codex"] : [target]))];
+}
+export async function installSkill(requested = "auto", options = {}) {
+    const env = options.env ?? process.env;
+    const detections = await detectHarnesses(env);
+    const targets = expandedTargets(Array.isArray(requested) ? requested : [requested]);
+    const selected = targets === "all"
+        ? detections
+        : targets === "auto"
+            ? detections.filter((item) => item.detected)
+            : targets.map((id) => detections.find((item) => item.id === id));
+    if (!selected.length) {
+        throw new Error("No supported coding harnesses detected. Name one explicitly or use `bxc skill install all`.");
+    }
+    const destinations = new Map();
+    for (const target of selected) {
+        const current = destinations.get(target.path);
+        if (current)
+            current.agents.push(target.label);
+        else
+            destinations.set(target.path, { agents: [target.label], path: target.path });
+    }
+    const installations = [...destinations.values()];
+    const planned = await Promise.all(installations.map(async (item) => {
+        if (!await exists(item.path))
+            return { ...item, status: "installed" };
+        if (options.force)
+            return { ...item, status: "updated" };
+        if (await matchesPackagedSkill(item.path))
+            return { ...item, status: "unchanged" };
+        throw new Error(`${item.path} already exists and differs; pass --force to replace it`);
+    }));
+    for (const item of planned) {
+        if (item.status === "unchanged")
+            continue;
+        await mkdir(path.dirname(item.path), { recursive: true });
+        const temporary = `${item.path}.tmp-${process.pid}`;
+        await rm(temporary, { recursive: true, force: true });
+        await cp(sourceSkill, temporary, { recursive: true });
+        if (options.force)
+            await rm(item.path, { recursive: true, force: true });
+        await rename(temporary, item.path);
+    }
+    return planned;
+}
+export async function removeSkill(requested = "auto", options = {}) {
+    const env = options.env ?? process.env;
+    const detections = await detectHarnesses(env);
+    const targets = expandedTargets(Array.isArray(requested) ? requested : [requested]);
+    const selected = targets === "all"
+        ? detections
+        : targets === "auto"
+            ? detections.filter((item) => item.detected || item.installed)
+            : targets.map((id) => detections.find((item) => item.id === id));
+    if (!selected.length) {
+        throw new Error("No supported coding harnesses detected. Name one explicitly or use `bxc skill remove all --yes`.");
+    }
+    const destinations = new Map();
+    for (const target of selected) {
+        const current = destinations.get(target.path);
+        if (current)
+            current.agents.push(target.label);
+        else
+            destinations.set(target.path, { agents: [target.label], path: target.path });
+    }
+    const removals = await Promise.all([...destinations.values()].map(async (item) => {
+        if (!await exists(item.path))
+            return { ...item, status: "missing" };
+        if (!options.force && !await matchesPackagedSkill(item.path)) {
+            throw new Error(`${item.path} differs from the packaged skill; pass --force to remove it`);
+        }
+        return { ...item, status: "removed" };
+    }));
+    for (const item of removals) {
+        if (item.status === "removed")
+            await rm(item.path, { recursive: true, force: true });
+    }
+    return removals;
+}
+export async function readSkill() {
+    const { readFile } = await import("node:fs/promises");
+    return readFile(path.join(sourceSkill, "SKILL.md"), "utf8");
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@boxcompute/cli",
+  "version": "0.1.1",
+  "description": "Connect local AI agents to BoxCompute sandboxes",
+  "keywords": [
+    "boxcompute",
+    "sandbox",
+    "ai-agent",
+    "cli"
+  ],
+  "homepage": "https://app.boxcompute.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boxcompute/web-agent.git",
+    "directory": "apps/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/boxcompute/web-agent/issues"
+  },
+  "type": "module",
+  "bin": {
+    "bxc": "dist/cli.js",
+    "bcompute": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "oxlint --max-warnings 0 src test",
+    "prepack": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^26.0.0",
+    "oxlint": "^1.75.0",
+    "typescript": "~6.0.2"
+  }
+}

package/skills/boxcompute-sandbox/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: boxcompute-sandbox
+description: Use the authenticated bxc CLI to run code, data work, builds, tests, or service experiments in an isolated BoxCompute workspace. Use when work needs remote compute or should not run directly on the user's machine; do not use for ordinary local file edits that need no execution.
+---
+
+# BoxCompute Sandbox
+
+Use `bxc` as the only interface. Authentication belongs to the human: if
+`bxc doctor` says the client is not authenticated, ask the user to run
+`bxc auth`; never request, read, print, or transmit their saved credential.
+
+## Choose the workspace
+
+Run `bxc --json sandboxes` and select the workspace whose name matches the
+task. Do not assume the first result is correct. If no workspace fits, tell the
+user to create one in BoxCompute; the CLI deliberately does not create account
+workspaces.
+
+Start or resume it with:
+
+```sh
+bxc --json sandbox start WORKSPACE_ID
+```
+
+The stable workspace ID is also the sandbox ID used by later commands.
+
+## Execute work
+
+Prefer argument-vector execution, which avoids a local shell:
+
+```sh
+bxc sandbox exec SANDBOX_ID -- python -m pytest
+bxc sandbox exec SANDBOX_ID --cwd /workspace/project -- npm test
+```
+
+Use `bash -lc` only when the remote operation genuinely needs shell syntax such
+as pipes or redirection. Paths must stay at `/workspace` or below it. Separate
+executions do not share shell variables or a changed working directory, so pass
+`--cwd` and `--env KEY=VALUE` explicitly when needed.
+
+Use `--json` when inspecting results programmatically. A non-zero command exit
+is task evidence, not a reason to repeat blindly: read stdout/stderr, correct
+the cause, and then run the revised command. Never send local secrets into the
+sandbox unless the user explicitly places those secrets in scope.
+
+## Lifecycle and safety
+
+- Inspect uncertain state with `bxc --json sandbox status SANDBOX_ID`.
+- Sandboxes persist across commands; do not destroy one merely because the
+  current task is finished.
+- `bxc sandbox delete SANDBOX_ID --yes` destroys the remote runtime and is
+  intentionally explicit. Use it only when the user asks to remove the runtime
+  or clearly designated it as disposable. The BoxCompute workspace remains.
+- The CLI does not retry mutating requests. If a connection drops during a
+  start or delete, inspect state before deciding what to do next.
+
+Summarize which workspace was used, the meaningful command results, and whether
+the sandbox was left running.

package/skills/boxcompute-sandbox/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "BoxCompute Sandbox"
+  short_description: "Run local AI work safely in BoxCompute"
+  default_prompt: "Use $boxcompute-sandbox to run this task in an isolated BoxCompute sandbox."
+  brand_color: "#CE704C"