Skip to content

v0.2.3

Latest

Choose a tag to compare

@kevin-orellana kevin-orellana released this 17 Nov 21:06
5ed679f

What's new in v0.2.3

Box Core v0.2.3 adds inbound services, request routing through backends, macOS file watching, and broader Linux tool support. It also adopts upstream Strands Shell. Read the breaking working-directory and history change before upgrading an existing box.

  • Inbound services: Run an agent that serves HTTP or another TCP service. In box.toml, enable [experimental-features] ingress = true and declare [[agent.ingress]] listeners with listen and workload_port. Each box supports up to five listeners. #272
  • Request backends: Route an outbound destination through [[egress.<name>.backends]], or a remote Model Context Protocol (MCP) server through [[mcp.<name>.backends]]. Policy still evaluates the original destination and server. Backend authentication supports a token or AWS request signing. At most one backend is supported per entry. #311, #413
  • HTTP upgrades and direct connections: Use [gateway] upgrade_http for selected hosts that need plain HTTP requests forwarded over HTTPS. Tools and local MCP servers configured with contain_egress = false can use their own proxy and certificate-trust settings. Their direct connections bypass gateway policy and credential injection. #411, #412
  • Shell and Python aliases: Box now uses a pinned upstream Strands Shell. The zsh, bash, sh, python3, and python aliases pass their caller's working directory to Shell. Python aliases run through Shell's Python command and require shell:exec permission before Python's own policy checks. Shell aliases forward piped or file input, with configurable command-text, output, and incoming-data limits under [limits.shell]. The command-text check also covers multiline submissions. #414, #417, #397, #401, #403
  • Tool and local-server startup: A bare tool name runs its declared executable, even when another installation appears first on PATH. MCP server commands accept absolute executable paths. Unmatched MCP helper commands can run as ordinary programs under the agent's grants. Local servers must pass their bound tool-grammar checks; a server installed after startup cannot acquire a missing grammar permit. #388, #377, #357, #386
  • MCP policy and responses: Completed calls are recorded under each tool's own action, with declared result fields available through output.structured. MCP handling preserves empty HTTP resource queries and rejects messages that carry both a method and a result. #391, #416, #299, #438
  • Address checks: Shell URL checks reject additional translated and platform-specific cloud metadata addresses before transport. #393
  • AWS credential resolution: Both aws:// and aws://PROFILE resolve through the AWS SDK. A named profile supports static credentials, credential_process, assume-role, and web identity, without falling back to the host's environment credentials or instance identity. Each SDK resolution has a five-second timeout. On macOS, the credential-daemon client uses an existing per-user socket, or the system socket when none exists; CREDSD_SOCKET still overrides that choice. #342, #415, #441
  • Opt-in macOS file watching: Set file-watching = true on the selected [agent], [tool.<name>], or local stdio [mcp.<name>] table. Each process opts in separately. This enables the macOS file-event service for development servers and other watchers, with the metadata disclosure described below. It defaults to false and has no effect on Linux. #430
  • Read-only file links: A filesystem read or read_file entry can name a symbolic link to a file, such as /usr/bin/cc. Box grants the resolved file and preserves the link's name as a read-only path. Directory links and links in write or executable grants remain refused. #456
  • Linux tool compatibility and networking: Permit the Linux operations that Go programs use to wait for children, tools use to copy or send files, and Cargo uses while downloading crates. To enable Box's experimental Linux x86-64 runtime, set the EXPERIMENTAL_X86_SUPPORT environment variable to TRUE. Gateway connections disable TCP batching of small writes on both sides. #447, #451, #455, #398, #457, #459
  • Linux build and test checks: The experimental x86-64 package now uses the Amazon Linux 2023 build environment and GNU C Library (glibc) 2.34, matching ARM64. Package checks verify all three executables against their target architecture and glibc baseline. Native x86-64 workspace and deterministic tests now participate in required continuous integration checks. #466, #446
  • Library integration: Callers can supply RunOptions::box_id so Box's stored identity and telemetry match the caller's identity. IDs fit the existing 32-byte name limit. The new strands_box::reserved_env function identifies environment names that Box reserves, including proxy and certificate-file names. #437, #454, #460
  • Diagnostics: Reject stored policy history dated more than five minutes ahead of the clock. Report failed or unfinished final telemetry exports once on standard error, without changing the exit status. The Kubernetes example diagnoses incompatible sandbox settings before launch. #410, #439, #384

Breaking change: shell working-directory paths and history

For ordinary shell:exec and shell:spawn actions, Box now reports working directories under the operator's home as ~/…. For example, when that home is /home/operator, a command in /home/operator/project reports ~/project to policy. The command still runs in the same directory. This behavior takes effect on upgrade; there is no separate opt-in setting.

Existing history rules can silently stop denying commands. Previously recorded events keep their absolute paths. A history condition that matches /home/operator/project misses new events containing ~/project. An unchanged rule can initially enforce its restriction through older matching events, then lose it when those events expire. Box accepts these history conditions without a warning.

Before upgrading an affected box:

  1. Review working-directory conditions. Check input.cwd conditions for ordinary shell actions, including expressions, patterns, and conditions on recorded events. Use ~/… below the operator's home when matching new events. Keep outside-home paths and working-directory values in tool-specific grammar actions absolute.
  2. Choose when to reset affected history rules. Changing a history rule's conditions resets its accumulated state, even if the new condition accepts both path spellings. Existing counts and history-based restrictions do not carry over to the changed rule. This release does not translate old events or migrate rule state. If you must retain that state, postpone upgrading the affected box.
  3. Update the policy and Box version together, then test the rules before resuming the workload. Verify an intended denial and an allowed control. For a history rule, record a new triggering event and confirm the expected restriction. Some absolute-home expressions load without warning, so successful startup alone does not verify matching.

See the policy upgrade limits and #296.

Other compatibility notes and limits

  • Upgrade all executable components together. The main executable and command helpers now use internal protocol version 9 instead of 7; mixed versions cannot communicate. Keep the complete archive together. Absolute MCP commands, inbound listeners, backends, explicit Shell size limits, HTTP upgrades, supplied box identities, and enabled file watching can write stored configurations that v0.2.2 cannot resume. Explicitly setting Shell size limits to their defaults also selects a newer format. Older builds reject the file-watching configuration key even when it is false; remove it from every process table before rollback. See stored configuration and rollback.
  • Opt-in macOS directory policy changed. In box.toml, [experimental-features] native-filesystem-policy = true enables experimental native file checks on macOS 27 or later. Opening a directory for reading now checks fs:read with context.input.operation == Box::FsReadOperation::"enumerate", instead of read_content. Update matching rules before upgrading an enabled box. A directory rename still requires source read_content; a rule that permits listing alone does not permit the rename. Linux release packages still refuse startup when this setting is true. See native filesystem operation meanings and #193.
  • Python aliases now require a Shell permit. Review policies that previously permitted Python alone. These aliases do not forward standard input. Shell command records now redact non-flag arguments, including literal paths. Long flags with values retain the flag name and redact the value; consumers must not expect literal argument text to remain visible. See Python aliases and command telemetry.
  • Forwarded Shell input defaults to 64 KiB. max_stdin must be positive. Beyond it, Box discards additional input and withholds end-of-input; a reader can wait until its deadline. Streaming commands may already have acted on the accepted prefix. Separately sandboxed tool programs and Lua commands do not receive this forwarded input. max_output applies to each output buffer, not total process memory. See Shell input limits.
  • Both AWS reference forms can execute credential_process outside the sandbox. Named profiles no longer provide a static-key-only boundary. Keep ~/.aws and its ancestors unwritable by untrusted workloads. A bare aws:// uses the host's default credential chain and warns on each signed request; a named profile pins the selected profile. AWS single sign-on and aws login profiles remain unsupported. See credential sources.
  • File watching can disclose denied names and activity. macOS file events can expose names and metadata outside the workspace and from past events. Filesystem deny rules do not fully filter that stream, although file-content and write restrictions still apply. Keep file-watching disabled when those names or events must remain confidential. See file-watching limits.
  • Remote MCP matching is host-based. List explicit destination hosts; wildcard destinations provide credential routing but do not select MCP checks. MCP matching ignores configured ports and paths, and equivalent host spellings belong in one server entry. Backend routing applies during box run; policy generate-schema refuses a configuration containing a remote MCP backend. See remote destination matching.
  • Network limits remain explicit. Inbound listeners have no caller policy check. On macOS, other processes can reach the agent's port directly; the network can reach it if the agent binds 0.0.0.0. HTTP upgrades leave the workload's connection unencrypted and still reject credential-matched requests with HTTP 403. HTTP history budgets count recorded outcomes when exchanges end; pending exchanges can let the total exceed the stated limit. See inbound connections, HTTP upgrades, and HTTP budget timing.
  • Library callers may need a source update. Code that initializes every RunOptions field must add box_id or use ..Default::default(). A supplied ID uses a 1–15-character name prefix, a hyphen, and 16 lowercase hexadecimal digits. The prefix accepts letters, digits, dots, underscores, and hyphens, and cannot start with a dot or hyphen. Omitting it preserves generated IDs. See #437 and #454.

Download

This release provides macOS Apple silicon and Amazon Linux 2023 ARM64 archives. Linux x86-64 remains a workflow artifact, not a published release package.

The downloader supports Linux x86-64 when the selected release publishes its archive and checksum. This tag omits that package, so x86-64 downloads stop instead of selecting ARM64 or an older release. #475

On either supported platform, download and verify this exact release:

curl -fsSL https://raw.githubusercontent.com/strands-agents/box/5ed679f10a4b8c21bbe84dac119034258d4633fc/download.sh | BOX_VERSION=v0.2.3 sh

The downloader verifies the archive against SHA256SUMS.txt and extracts it into ./box-core. It leaves PATH and system directories unchanged. Set BOX_DOWNLOAD_DIR=/some/path to choose another directory. Write box.toml and its policy, then run ./box-core/box run --config ./box.toml.

The macOS archive contains Box.app, a launcher, and helper links into the signed and notarized bundle. Keep the directory intact. The Linux archive contains box beside its helpers and requires glibc 2.34 or newer, libgcc, and permission to use Box's namespaces, mounts, and system-call filters. Package availability does not establish security acceptance.

Full changes since v0.2.2