@boxcompute/cli 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+This file records user-visible changes to the BoxCompute CLI. GitHub Releases
+use the same notes and bind them to the exact source commit.
+
+## [0.2.4] - 2026-09-09
+
+`bxc sandbox exec` now leaves arguments after `--` entirely to the program
+running inside the sandbox.
+
+### CLI users
+
+- Commands such as `bxc sandbox exec SANDBOX_ID -- python --version --json`
+  now pass `--version` and `--json` to Python instead of treating them as
+  global `bxc` options.
+- No configuration changes are required. Upgrade normally with `bxc update`.
+
+### Security
+
+No security-relevant changes.
+
+## [0.2.3] - 2026-09-06
+
+- Added access to retained sandbox logs after runtime deletion.
+
+## [0.2.2] - 2026-09-05
+
+- Added `bxc update` and its `bxc up` alias.
+
+## [0.2.1] - 2026-09-05
+
+- Improved release validation and managed skill updates.
+
+## [0.2.0] - 2026-09-04
+
+- Added the multi-instance Sandbox API v2 commands.
+
+## [0.1.1] - 2026-09-04
+
+- Initial public npm release with browser login and managed agent skills.

package/README.md

@@ -48,6 +48,7 @@ bxc workspaces
 bxc sandboxes
 bxc sandbox start WORKSPACE_ID
 # Use the returned sandbox instance ID for later commands.
+bxc sandbox logs SANDBOX_ID --source execute
 bxc sandbox exec SANDBOX_ID -- python -m pytest
 ```
 
@@ -69,3 +70,30 @@ bxc update
 saved BoxCompute credential and refreshes untouched managed skills before the
 client's next agent session. The new CLI uses v2 for multi-instance sandboxes
 and gives a server-first upgrade message if it reaches an older deployment.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run typecheck
+bun test
+bun run lint
+bun run build
+```
+
+The application-side authentication and customer Sandbox API implementations
+live in the private `boxcompute/web-agent` repository. Changes to either side of
+that contract must remain backward compatible during rollout: deploy the server
+first, then publish the CLI.
+
+## Releases
+
+Every user-visible change is recorded in [CHANGELOG.md](CHANGELOG.md). Releases
+use semantic `vMAJOR.MINOR.PATCH` tags and are published from `main` by the
+protected `Publish BoxCompute CLI` workflow. npm trusted publishing supplies a
+short-lived release credential; the repository stores no npm token.
+
+## License
+
+Copyright © 2026 BoxCompute. All rights reserved. The source is publicly
+visible, but it is not offered under an open-source license.

package/dist/cli.js

@@ -26,6 +26,7 @@ Commands:
   sandbox                         Manage isolated BoxCompute sandboxes
     start                         Create and start a workspace sandbox
     status                        Inspect one sandbox
+    logs                          Read current or retained sandbox logs
     exec                          Execute a program inside a sandbox
     delete                        [alias: rm] Destroy the runtime; the workspace remains
   skill                           [alias: skills] Manage coding-harness skills
@@ -54,6 +55,7 @@ Examples:
   $ bxc skill install
   $ bxc workspaces
   $ bxc sandbox start WORKSPACE_ID
+  $ bxc sandbox logs SANDBOX_ID --source execute
   $ bxc sandbox exec SANDBOX_ID -- python -m pytest
 
 Compatibility:
@@ -68,6 +70,7 @@ Commands:
 
   start WORKSPACE_ID              Create and start a new sandbox instance
   status SANDBOX_ID               Inspect one sandbox
+  logs SANDBOX_ID [options]       Read logs without starting the runtime
   exec SANDBOX_ID [options] -- PROGRAM [ARG...]
                                   Execute a program inside a sandbox
   delete SANDBOX_ID --yes         [alias: rm] Destroy the runtime; keep the workspace
@@ -78,6 +81,15 @@ Exec options:
   --env KEY=VALUE                 Set an environment variable; repeatable
   --timeout SECONDS               Command timeout
   --max-output-bytes BYTES        Maximum captured output
+
+Log options:
+
+  --since TIMESTAMP               Include entries at or after an RFC 3339 time
+  --until TIMESTAMP               Include entries before an RFC 3339 time
+  --stream stdout|stderr          Filter by output stream
+  --source workload|execute|process
+                                  Filter by log source
+  --limit ENTRIES                 Maximum entries (default: 1000, max: 5000)
 `;
 const skillHelp = `Manage coding-harness skills
 
@@ -228,8 +240,10 @@ function flag(tokens, name) {
     tokens.splice(index, 1);
     return true;
 }
-function anyFlag(tokens, ...names) {
-    const index = tokens.findIndex((token) => names.includes(token));
+function globalFlag(tokens, ...names) {
+    const separator = tokens.indexOf("--");
+    const boundary = separator < 0 ? tokens.length : separator;
+    const index = tokens.findIndex((token, position) => position < boundary && names.includes(token));
     if (index < 0)
         return false;
     tokens.splice(index, 1);
@@ -243,6 +257,21 @@ function positive(value, name) {
         throw new UsageError(`${name} must be a positive integer`);
     return parsed;
 }
+function timestamp(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.valueOf()))
+        throw new UsageError(`${name} must be an RFC 3339 timestamp`);
+    return parsed.toISOString();
+}
+function oneOf(value, name, values) {
+    if (value === undefined)
+        return undefined;
+    if (!values.includes(value))
+        throw new UsageError(`${name} must be one of: ${values.join(", ")}`);
+    return value;
+}
 function environment(tokens) {
     const values = [];
     for (;;) {
@@ -338,6 +367,21 @@ function executionOutput(io, json, sandboxId, result) {
     }
     return result.exitCode ?? 1;
 }
+function logsOutput(io, json, logs) {
+    if (json) {
+        emit(io, true, { logs }, "");
+        return 0;
+    }
+    if (!logs.entries.length)
+        write(io.stdout, "No logs found.\n");
+    for (const entry of logs.entries) {
+        const process = entry.process_id ? ` ${entry.process_id}` : "";
+        write(io.stdout, `${entry.timestamp}\t${entry.stream}\t${entry.source}${process}\t${entry.message}\n`);
+    }
+    write(io.stderr, `sandbox=${logs.sandbox_id} entries=${logs.entries.length} retentionSeconds=${logs.retention_seconds}` +
+        `${logs.truncated ? " truncated=true" : ""}\n`);
+    return 0;
+}
 export async function runCli(argv, supplied = {}) {
     const env = supplied.env ?? process.env;
     const io = supplied.io ?? { stdout: process.stdout, stderr: process.stderr };
@@ -356,13 +400,13 @@ export async function runCli(argv, supplied = {}) {
     const skillText = supplied.readSkill ?? readSkill;
     const syncSkills = supplied.syncManagedSkills ?? syncManagedSkills;
     const args = [...argv];
-    const json = flag(args, "json");
-    const versionRequested = args[0] === "version" || anyFlag(args, "--version", "-V", "-v");
+    const json = globalFlag(args, "--json");
+    const versionRequested = args[0] === "version" || globalFlag(args, "--version", "-V", "-v");
     if (versionRequested) {
         emit(io, json, { version: CLI_VERSION }, `${CLI_VERSION}\n`);
         return 0;
     }
-    const helpRequested = anyFlag(args, "--help", "-h");
+    const helpRequested = globalFlag(args, "--help", "-h");
     if (!args.length || args[0] === "help" || helpRequested) {
         const helpTarget = args[0] === "help" ? args[1] : args[0];
         write(io.stdout, helpFor(helpTarget));
@@ -534,6 +578,20 @@ export async function runCli(argv, supplied = {}) {
         emit(io, json, { sandbox }, sandboxLine(sandbox));
         return 0;
     }
+    if (action === "logs") {
+        const since = timestamp(option(args, "since"), "--since");
+        const until = timestamp(option(args, "until"), "--until");
+        const stream = oneOf(option(args, "stream"), "--stream", ["stdout", "stderr"]);
+        const source = oneOf(option(args, "source"), "--source", ["workload", "execute", "process"]);
+        const limit = positive(option(args, "limit"), "--limit");
+        if (limit !== undefined && limit > 5_000)
+            throw new UsageError("--limit must be 5000 or fewer");
+        if (since && until && since >= until)
+            throw new UsageError("--since must be earlier than --until");
+        if (args.length)
+            throw new UsageError(`Unknown sandbox logs option: ${args[0]}`);
+        return logsOutput(io, json, await client.logs(id, { since, until, stream, source, limit }));
+    }
     if (action === "delete") {
         if (!flag(args, "yes") || args.length)
             throw new UsageError("sandbox delete requires SANDBOX_ID --yes");

package/dist/client.d.ts

@@ -5,6 +5,7 @@ export type Sandbox = {
     name: string;
     state: "cold" | "running";
     runtimeId: string | null;
+    retainedRuntimeId: string | null;
     image: string | null;
     createdAt: number;
     lastUsedAt: number | null;
@@ -23,6 +24,20 @@ export type Execution = {
     stderrTruncated: boolean;
     wallTimeSeconds: number;
 };
+export type SandboxLogEntry = {
+    timestamp: string;
+    stream: "stdout" | "stderr";
+    source: "workload" | "execute" | "process";
+    message: string;
+    pod_uid: string;
+    process_id?: string;
+};
+export type SandboxLogs = {
+    sandbox_id: string;
+    entries: SandboxLogEntry[];
+    truncated: boolean;
+    retention_seconds: number;
+};
 export declare class BoxComputeHttpError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
@@ -46,5 +61,12 @@ export declare class BoxComputeClient {
         maxOutputBytes?: number;
         env?: Record<string, string>;
     }): Promise<Execution>;
+    logs(id: string, input?: {
+        since?: string;
+        until?: string;
+        stream?: "stdout" | "stderr";
+        source?: "workload" | "execute" | "process";
+        limit?: number;
+    }): Promise<SandboxLogs>;
     delete(id: string): Promise<void>;
 }

package/dist/client.js

@@ -66,6 +66,21 @@ export class BoxComputeClient {
             body: JSON.stringify(input),
         })).result;
     }
+    async logs(id, input = {}) {
+        const query = new URLSearchParams();
+        if (input.since)
+            query.set("since", input.since);
+        if (input.until)
+            query.set("until", input.until);
+        if (input.stream)
+            query.set("stream", input.stream);
+        if (input.source)
+            query.set("source", input.source);
+        if (input.limit !== undefined)
+            query.set("limit", String(input.limit));
+        const suffix = query.size ? `?${query}` : "";
+        return (await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}/logs${suffix}`)).logs;
+    }
     async delete(id) {
         await this.request(`/api/v2/sandboxes/${encodeURIComponent(id)}`, { method: "DELETE" });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxcompute/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Connect local AI agents to BoxCompute sandboxes",
   "keywords": [
     "boxcompute",
@@ -11,18 +11,19 @@
   "homepage": "https://app.boxcompute.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/boxcompute/web-agent.git",
-    "directory": "apps/cli"
+    "url": "git+https://github.com/boxcompute/cli.git"
   },
   "bugs": {
-    "url": "https://github.com/boxcompute/web-agent/issues"
+    "url": "https://github.com/boxcompute/cli/issues"
   },
+  "license": "UNLICENSED",
   "type": "module",
   "bin": {
     "bxc": "dist/cli.js",
     "bcompute": "dist/cli.js"
   },
   "files": [
+    "CHANGELOG.md",
     "dist",
     "skills"
   ],
@@ -32,6 +33,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "packageManager": "bun@1.3.14",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "lint": "oxlint --max-warnings 0 src test",

package/skills/boxcompute-sandbox/SKILL.md

@@ -44,6 +44,11 @@ sandbox unless the user explicitly places those secrets in scope.
 ## Lifecycle and safety
 
 - Inspect uncertain state with `bxc --json sandbox status SANDBOX_ID`.
+- Read runtime output with `bxc sandbox logs SANDBOX_ID`. Add `--json` for
+  structured entries or narrow results with `--since`, `--until`, `--stream`,
+  `--source`, and `--limit`. Log reads do not start stopped compute, and remain
+  available for the provider's nominal 30-day retention period after deletion;
+  storage pressure may shorten that period, so logs are not an archive.
 - 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