From bcc020bfd4f51b46f30e9b2574a97b80208b8be9 Mon Sep 17 00:00:00 2001 From: Varun Gunda Date: Fri, 20 Nov 2026 09:52:56 -0800 Subject: [PATCH 1/2] docs(box): Bring the local test guide up to date with box-integration-development Port the sections of the box-integration-development guide that the box-integration code supports: Install box with the pinned 0.1.11-mquang.preview.9 (now with a macOS build), the settings checks, the dev step, the step 9 live checks by gateway ID and provider name, the box telemetry and gateway logs step, and the full tear down. Keep the names and behavior of box-integration: the gateway -box-egress bound by boundRuntime, --containment, the strict box.version pin, the box-release.env of a container, and the build behavior for a rotated GITHUB_TOKEN. --- docs/box-local-testing.md | 423 ++++++++++++++++++++++++++++++++++---- 1 file changed, 382 insertions(+), 41 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index f6af0c4b4..674f42405 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -20,11 +20,8 @@ Runtime. Each box runtime names its box release in `agentcore.json` with `~/.agentcore/box/`, check its SHA-256s, and stage it into the zip, for a CodeZip runtime. For a container they write the release and its checksum into `.box-dist/box-release.env` instead. A container image downloads the Linux build while it builds, under `agentcore dev` too. For a -CodeZip agent, `agentcore dev` runs the `box` on your PATH: download the build for your machine -from the release, unpack it into a folder, and add that folder to your PATH. The pinned release, -`0.1.11-mquang.preview.9`, has only the Linux arm64 build. On macOS, use the macOS build of -`0.1.11-linux-preview.7`, the first box that reads the profiles the CLI writes, or of a later release. -No local box checkout is needed. +CodeZip agent, `agentcore dev` runs the `box` on your PATH: install it as in +[Install box](#install-box). No local box checkout is needed. Dev, build and deploy run a runtime's agent in a box only when `agentcore.json` has `"projectType": "box"` and the runtime has `"box": { "version": ... }`. `create` writes both, and @@ -33,34 +30,109 @@ only for the box templates. The runtime's entry point and Dockerfile never decid `"projectType": "box"` stops dev with `agentcore.json has no "projectType": "box"`. `box.version` must be the box version the CLI pins in -`src/core/project/backends/boxRelease.json`; build, deploy and container `dev` stop on any other version. To try an -unreleased box build, publish it as a pre-release with the same file names and run -`bun scripts/bump-box-release.ts --box ` in your CLI checkout, then set `box.version` to it. +`src/core/project/backends/boxRelease.json`; build, deploy and container `dev` stop on any other +version. To try an unreleased box build, publish it as a pre-release with the same file names and +run `bun scripts/bump-box-release.ts --box ` in your CLI checkout, then set `box.version` +to it. ## Prerequisites - A local checkout of the CLI and of `@aws/agentcore-cdk`. +- `box` `0.1.11-mquang.preview.9` on your `PATH`, the release the CLI pins. The oldest box that + works is `0.1.11-linux-preview.7`, the first release with + [strands-agents/staging-boxy#625](https://github.com/strands-agents/staging-boxy/pull/625), which + the default telemetry target of the AgentCore Runtime profile needs. Build, deploy and dev run it + to read the box profile with `box profile show --format json --full`, and CodeZip dev runs the + agent with it. See [Install box](#install-box). - AWS credentials for a **dev or test** account. Build writes the Box gateway's Bedrock and Memory targets for `AWS_REGION` (else your AWS profile's region), and deploy for its target's region. - `bun` for the CLI, `npm` for the generated CDK app. +## Install box + +box ships as a release archive per machine on +[mquang-amazon/box-releases](https://github.com/mquang-amazon/box-releases). There are builds for +macOS on an Apple chip (`aarch64-apple-darwin`) and Linux arm64 (`aarch64-unknown-linux-gnu`); there +is no x86 build yet. Each archive unpacks flat: `box`, its two helpers, `release.json`, and +`resources/` (box's packs, which it finds beside itself). + +Download the archive for your machine, check it, and unpack it into a versioned folder. + +macOS on an Apple chip: + +``` +mkdir -p ~/.local/share/box/0.1.11-mquang.preview.9 && cd ~/.local/share/box/0.1.11-mquang.preview.9 +curl -fSLO https://github.com/mquang-amazon/box-releases/releases/download/v0.1.11-mquang.preview.9/box-v0.1.11-mquang.preview.9-aarch64-apple-darwin.tar.gz +curl -fSLO https://github.com/mquang-amazon/box-releases/releases/download/v0.1.11-mquang.preview.9/SHA256SUMS.txt +grep aarch64-apple-darwin SHA256SUMS.txt | shasum -a 256 -c - +tar -xzf box-v0.1.11-mquang.preview.9-aarch64-apple-darwin.tar.gz +``` + +Linux arm64: + +``` +mkdir -p ~/.local/share/box/0.1.11-mquang.preview.9 && cd ~/.local/share/box/0.1.11-mquang.preview.9 +curl -fSLO https://github.com/mquang-amazon/box-releases/releases/download/v0.1.11-mquang.preview.9/box-v0.1.11-mquang.preview.9-aarch64-unknown-linux-gnu.tar.gz +curl -fSLO https://github.com/mquang-amazon/box-releases/releases/download/v0.1.11-mquang.preview.9/SHA256SUMS.txt +grep aarch64-unknown-linux-gnu SHA256SUMS.txt | sha256sum -c - +tar -xzf box-v0.1.11-mquang.preview.9-aarch64-unknown-linux-gnu.tar.gz +``` + +The check must print `OK`. + +Put the folder first on your `PATH`, for this shell and for new ones (use `~/.bashrc` for bash): + +``` +export PATH="$HOME/.local/share/box/0.1.11-mquang.preview.9:$PATH" +grep -q 'share/box/0.1.11-mquang.preview.9' ~/.zshrc || echo 'export PATH="$HOME/.local/share/box/0.1.11-mquang.preview.9:$PATH"' >> ~/.zshrc +``` + +The `grep -q ... ||` adds the line only once, so running it again does not repeat it. When you move +to a newer release, edit that line in `~/.zshrc` rather than adding another. + +Check it: + +``` +which box +box --version +``` + +- `which box` must name the folder you unpacked into. An older `box` earlier on your `PATH` (a + source build, or Box Core's `box` in `/usr/local/bin`) wins otherwise. +- `box --version` must print `box 0.1.11-mquang.preview.9`, the release the CLI pins in + `src/core/project/backends/boxRelease.json`. The oldest box that build, deploy and dev accept is + `0.1.11-linux-preview.7`. +- On macOS, if Gatekeeper refuses to run `box`, clear the download flag with + `xattr -dr com.apple.quarantine "$HOME/.local/share/box/0.1.11-mquang.preview.9"`. + +To move to a newer release, unpack it into its own folder the same way and change the `PATH` line +to that folder. + ## Settings -Set these once per shell. Change the values for your machine. +Set these once per shell. Change the values for your machine: `CLI` is the CLI run from source in +your workspace checkout, `L3` is the local L3 constructs checkout, and `DEMO` and `PROJECT` say +where the demo project goes. Use absolute paths: the steps below `cd` into other folders, where a +relative path no longer resolves (`bun` then says `Module not found "./agentcore-cli/src/index.ts"`). +Replace `/path/to/workspace` with the folder that holds both checkouts: ``` -# The CLI, run from source. Point at your workspace checkout. CLI=/path/to/workspace/agentcore-cli/src/index.ts - -# The local L3 constructs checkout. L3=/path/to/workspace/agentcore-l3-cdk-constructs - -# Where the demo project goes. DEMO=/tmp/cliDemo PROJECT=cliDemo ``` +Check that both paths exist. This prints `ok`, or nothing if a placeholder is still there: + +``` +test -f "$CLI" && test -d "$L3" && echo ok +``` + +Write `$HOME`, not `~`, inside quotes: the shell expands `~` only outside quotes, so `CLI="~/..."` +makes bun look for a folder named `~`. + ## Install the CLI's dependencies The CLI runs from source, so it needs its own `node_modules`. Install them once in the @@ -120,28 +192,40 @@ printf '\n[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env: ### What build and deploy do with the box profile -Build and deploy read each runtime's own `.box//local/profile.toml` and the policy files -it lists under `policies`, and turn them into that runtime's Box network. They change nothing in -`.box//local/`. They stage the Runtime profile, its policy files, and box in the -`.box-dist/` folder of the code folder or of the build context, and write a copy of the profile, -the generated packs, and the policy files into `.box//aws/` for you to read. - -- **Gateway targets.** Each host or `host:port` that an `[egress]` entry or a policy permit - names, and that the policy allows at least one request to, gets one passthrough target on - `-box-egress`. A host the gateway already has a target for keeps that target. Build owns +Build and deploy run `box profile show .box//local/profile.toml --format json --full` in +the project folder, with the `box` on your `PATH`, and turn the `box.toml` and `policy.dw` that Box +resolves the profile to into the runtime's Box network. Every pack, option, and rule Box adds is +already in them, so any pack works. They change nothing in `.box//local/`. They stage the +Runtime profile, its policy files, and box in the `.box-dist/` folder of the code folder or of the +build context, and write a copy of the profile, the generated packs, and the policy files into +`.box//aws/` for you to read. + +Box `0.1.11-linux-preview.7` names its packs `@box/base`, `@box/bedrock`, and `@box/agentcore`. +For a profile that names a pack or a plugin `box/`, build stops and gives each `@box/` +name. + +- **Gateway targets.** Each host or `host:port` that an `[egress]` entry, an `[mcp]` server + with `type = "http"`, or a policy permit names, and that the policy allows at least one + request to, gets one passthrough target on `-box-egress`. The target of an MCP server is + `egress-`. Its `protocolType` is `CUSTOM`, thus only Box makes the decision on each + `mcp:call`. A host the gateway already has a target for keeps that target. Build owns only the targets whose name starts with `egress-`: it adds them, changes them, and removes one when no host needs it. It never changes another target. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. -- **Failures.** A wildcard host, a plain-HTTP-only host, an unsupported secret or pack, an - MCP server over HTTP, and similar cases stop build and deploy. The error lists every - failure with its rule or entry and its `file:line:column`, and nothing is written. +- **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard + host, a plain-HTTP-only host, an unsupported secret, an MCP server that names more than one + host, a path, or a port other than 443, and similar cases stop them too. The error starts with `Build stopped:` or `Deploy stopped:` and the + number of problems, then gives one line for each problem: its `file:line:column` in your + profile or policy file, what is wrong, and how to fix it. A rule of your policy file is found + by its `@id`. For a rule that Box adds, the line names the entry that makes Box add it, such as + `[egress.github]`. Nothing is written. - **Warnings.** Build warns when Box enforces rules that the gateway does not (a path, method, or forbid), when an entry's host gets no target, and when a target is signed for an AWS service that no policy of the gateway's role grants. - **The AgentCore Runtime profile.** Build derives `.box-dist/profile.toml` from the local - profile. Each key of the local profile stays, and build changes - only what must differ on AgentCore Runtime: + profile. Each key of the local profile stays, and build changes only what must differ on + AgentCore Runtime: - each `[egress]` host with a gateway target becomes one route to `-box-egress`: the first host of an entry keeps the name of the entry, so a pack's own entry of that name merges with it, and each other host gets `[egress.]`; an HTTP `[mcp.]` server gets the @@ -193,7 +277,114 @@ rm -rf node_modules/@aws/agentcore-cdk npm install "$L3"/aws-agentcore-cdk-*.tgz ``` -## 6. Build +## 6. Test locally with `agentcore dev` + +`agentcore dev` runs the agent in a box on your machine, so you can try the project before you +deploy. It deploys nothing. The agent signs its Bedrock calls with your `[default]` AWS profile +(`secret.ref = "aws://default"` in `.box/agent/local/profile.toml`), and Memory is off +(`LOCAL_DEV=1`). + +Dev runs an agent in a box only in a Box project, as build and deploy do: `agentcore.json` must +have `"projectType": "box"`, which `create` writes for the box templates. Without it, dev runs a +plain runtime the usual way, and stops on one that starts box (a CodeZip `start.py` entrypoint, or +a Dockerfile that installs box) with `agentcore.json has no "projectType": "box"`. + +### Which box builds exist + +The box release has these builds: + +| Machine | Build | CodeZip dev | Container dev | +| ------------------- | ------------------------------------------ | ----------- | ------------- | +| macOS, Apple chip | `box-v-aarch64-apple-darwin` | yes | yes | +| Linux, arm64 | `box-v-aarch64-unknown-linux-gnu` | yes | yes | +| Linux or macOS, x86 | none | no | no | + +- The **container** image always uses the Linux arm64 build, because AgentCore Runtime is arm64. + It runs on an Apple chip Mac through Finch or Docker, and on an arm64 Linux host. An x86 host + would need to emulate arm64. +- **CodeZip** dev runs the `box` on your `PATH` natively, so it needs the build for your machine. + On an arm64 Linux host it uses the same Linux build as the Runtime. +- Build and deploy need a `box` on your `PATH` on every machine, to read the profile. So for now + build and deploy work only on an Apple chip Mac or an arm64 Linux host. + +### Before you start + +In the shell you run dev from: + +``` +box --version +aws sts get-caller-identity +``` + +- `box --version` must print `0.1.11-linux-preview.7` or later. Dev and build read the profile with + `box profile show --format json --full`. The AgentCore Runtime profile signs each Box gateway + backend for `${{ inputs.aws.region }}`, and its default telemetry target reads one key of + `OTEL_EXPORTER_OTLP_LOGS_HEADERS`. A box release before it cannot do all of these. +- The `[default]` profile must hold fresh credentials, because box reads them when dev starts. + After you refresh them, restart dev. + +### Run dev + +In the project from step 3, start dev. If you added the `[egress.github]` entry in step 4, first +export `GITHUB_TOKEN`, which that entry reads. A placeholder value is enough for the local check, as +in step 7: + +``` +cd "$DEMO/$PROJECT" +export GITHUB_TOKEN=ghp_demo_value +bun run "$CLI" dev +``` + +Dev hands each `env://` key of the box profile (an `[egress]` route's or an `[mcp]` server's) to +`box run` from your shell, and writes it nowhere. A value you put in `agentcore/.env.local` is used +when the shell has none. If neither has it, dev warns, naming the variable and how to set it, and box +then refuses to start (`credential variable GITHUB_TOKEN is not set`). A variable set without +`export` stays in the shell and does not reach dev: export it, or set it on the same line +(`GITHUB_TOKEN=... bun run "$CLI" dev`). + +Then, in a second shell in the project folder: + +``` +bun run "$CLI" invoke --local --runtime agent --payload '{"prompt":"What is 17 times 23?"}' +``` + +**Container template** (`agent-python-strands-box-container`, the one step 3 creates): + +- Dev builds the image with Docker, Podman or Finch. Set `AGENTCORE_CONTAINER_TOOL=finch` (or + `docker`, `podman`) to pick one. The image downloads the Linux box release while it builds. +- Dev passes your resolved AWS credentials into the container as profile `default`, and refreshes + them while it runs. +- Invoke once the dev output shows `0.0.0.0:8080 is relayed to the agent's port 8081`. +- The container runs with `--cap-add SYS_ADMIN` and unconfined seccomp, AppArmor and system paths, + which box's Linux sandbox needs. A container tool that refuses these flags cannot run it. +- The agent has read-only access to `/app`, plus exec on `/app/.venv`, so it can run its venv but + not change it. + +**CodeZip template** (`agent-python-strands-box`; create it in step 3 with +`--template agent-python-strands-box`): + +- Dev runs `box run .box//local/profile.toml` in the project folder with the `box` on + your `PATH`. The box listens on 8080 and relays to the agent on 8081. +- Invoke once the dev output shows `Uvicorn running on http://127.0.0.1:8081`. +- Dev needs the agent's venv: `create` runs `uv sync` in `app/agent`, on a uv-managed Python in + `~/.local/share/uv/python`, the only Python folder the profile lets box run. With + `--skip-install`, or to rebuild the venv, run this there first: + `UV_MANAGED_PYTHON=1 UV_PYTHON_INSTALL_DIR="$HOME/.local/share/uv/python" uv sync`. +- Port 8080 must be free. Dev refuses another port, because the profile's ingress listens on 8080. +- On macOS the box runs under Seatbelt, which cannot start inside another sandbox. Run dev from a + normal terminal, not from an agent's sandboxed shell. + +### What to check + +- The answer comes back from `invoke --local`. +- The dev output shows box starting the agent: `box: running profile cliDemo` (your `$PROJECT`) and the + `[agent]` filesystem summary, with `deny_write .../.venv (read-only)` for CodeZip. +- With the step 4 `[egress]` entry, calls to its host go out, and calls to other hosts are blocked + (`ProxyConnectionError ... 127.0.0.1:` in the agent's log means box blocked the host). + +Stop dev with Ctrl+C before you build. + +## 7. Build Export `GITHUB_TOKEN` before build. Build reads it and writes its value into `agentcore/.env.local` under the credential's reserved name `AGENTCORE_CREDENTIAL_GITHUB`. @@ -220,10 +411,10 @@ Run 'agentcore deploy' to provision the credential and build the project. This is expected. An `env://` credential must exist in AgentCore Identity before synthesis can resolve it, and only `deploy` provisions it. So on the **first** run with an egress credential, -skip straight to step 7: `deploy` provisions the credential and then builds in one step (keep +skip straight to step 8: `deploy` provisions the credential and then builds in one step (keep `GITHUB_TOKEN` exported). After that first deploy, `build` runs standalone as above. -## 7. Deploy +## 8. Deploy ``` bun run "$CLI" deploy @@ -232,33 +423,183 @@ bun run "$CLI" deploy Deploy synthesizes the CDK app you linked in step 5, so the stack uses your local L3 constructs. The first deploy makes the `default` target from your account and region. -## 8. Verify the gateway, its targets, and the credential +## 9. Verify the gateway, its targets, and the credential Local checks, in `agentcore/agentcore.json`: - `"projectType": "box"`. -- A gateway named `agent-box-egress` with a `bedrock` passthrough target in the deploy region, and an - `egress-github` target for `https://api.github.com`. +- A gateway named `agent-box-egress` with a `bedrock` passthrough target in the deploy region, and + an `egress-github` target for `https://api.github.com`. - A credential named `github` with `authorizerType: ApiKeyCredentialProvider`. -Live checks, after deploy: +Live checks, after deploy. Deploy names each AWS resource after the project and the deploy target +(`default`), so the names differ from those in `agentcore.json`: + +- The Box gateway `agent-box-egress` deploys as `-default-agent-box-egress`, for example + `cliDemo-default-agent-box-egress`. Its ID is that name in lowercase with a suffix, and is a + stack output. +- The credential `github` deploys as the API key credential provider `_default_github`, + for example `cliDemo_default_github`. ``` -bun run "$CLI" gateway list -bun run "$CLI" identity api-key-credential-provider get --name github +GATEWAY_ID=$(aws cloudformation describe-stacks --stack-name "AgentCore-$PROJECT-default" --query "Stacks[0].Outputs[?starts_with(OutputKey, 'ApplicationGatewayAgentBoxEgressIdOutput')].OutputValue" --output text) +echo "$GATEWAY_ID" +bun run "$CLI" gateway get --id "$GATEWAY_ID" +bun run "$CLI" identity api-key-credential-provider get --name "${PROJECT}_default_github" +``` + +`gateway list` shows every gateway in the account and region, not only this project's, so look +the Box gateway up by its ID as above. + +## 10. Read box telemetry and gateway logs in CloudWatch + +On AgentCore Runtime, box sends each policy decision (permit, deny, trace) to the log group of the +Runtime, `/aws/bedrock-agentcore/runtimes/-DEFAULT`, stream `otel-rt-logs`. When the box +profile of the agent has no `cloudwatch_logs` target, build adds the target `[telemetry.agentcore]` +to the Runtime profile. If the profile has a target with the name `agentcore`, the name is +`[telemetry.agentcore_default]`. When the run starts, box fills the region of the target from +`AWS_REGION`, and its log group and stream from `OTEL_EXPORTER_OTLP_LOGS_HEADERS`. The target sends +the deny, permit, and trace records, and box signs it with the execution role. + +The CLI and the L3 constructs make no log group for box. The role that the CDK makes for the +runtime can write to the log group of the Runtime, thus build adds no grant for it. A runtime that +names an `executionRoleArn` must have `logs:CreateLogStream` and `logs:PutLogEvents` on +`/aws/bedrock-agentcore/runtimes/*`. + +The `logs runtime` command finds that log group from the runtime name: + +```sh +cd "$DEMO/$PROJECT" +bun run "$CLI" logs runtime --name agent --since 15m --query '"strands.box.policy.verdict"' +``` + +Each record is one decision, with `strands.box.policy.verdict`, `.rule`, and `.resource`. To show +only the deny decisions, use `--query '"deny"'`. + +Deploy always sends the `APPLICATION_LOGS` of each Box gateway to +`/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/`. The gateway sends no +traces to X-Ray. Read the gateway logs with the gateway ID from step 9: + +```sh +aws logs tail "/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/$GATEWAY_ID" --since 15m ``` -## 9. Tear down +To replace the default target with a log group that you make: -Deploy bills you while resources exist. Remove them when done. +1. Set the region of the log group, then make the log group and the log stream. Box does not make + them, and deploy does not make them. + + ```sh + REGION=us-west-2 + aws logs create-log-group --region "$REGION" --log-group-name "/aws/box/$PROJECT" + aws logs create-log-stream --region "$REGION" --log-group-name "/aws/box/$PROJECT" --log-stream-name agent + ``` + +2. Add a target to the box profile of the agent, `.box/agent/local/profile.toml`. Set `region` to + `$REGION`, the region of the log group: + + ```toml + [telemetry.logs] + kind = "cloudwatch_logs" + region = "us-west-2" # your $REGION + log_group = "/aws/box/cliDemo" # your $PROJECT + log_stream = "agent" + include = ["deny", "permit", "trace"] + secret.ref = "aws://" + ``` + + If the target has no `region`, build writes the region of the `default` target in + `agentcore/aws-targets.json` into the Runtime profile, or the build region when there is no such + target, and deploy writes the region of its deploy target. Box does not accept a CloudWatch + target with no region. Thus `agentcore dev` cannot run the profile until you add `region`. + +3. Deploy the project: + + ```sh + cd "$DEMO/$PROJECT" + bun run "$CLI" deploy + ``` + + Build copies the table into the Runtime profile, where it replaces the default target. A + `cloudwatch_traces` target or a third-party target does not replace the default target. On + AgentCore Runtime, box signs this target with the execution role. Build also writes one policy + file for each box runtime, `agentcore/box-telemetry-policy-.json`, here + `box-telemetry-policy-agent.json`. It adds the file to the `additionalPolicies` of that runtime. + The file gives the role `logs:PutLogEvents` on the stream of each `cloudwatch_logs` target, and + `xray:PutSpans` and `xray:PutTraceSegments` for a `cloudwatch_traces` target. + +4. Invoke the agent, then read the records: + + ```sh + bun run "$CLI" invoke --runtime agent --payload '{"prompt":"What is 17 times 23?"}' + aws logs tail "/aws/box/$PROJECT" --region "$REGION" --since 15m + ``` + + To show only the deny decisions, add `--filter-pattern '"deny"'`. + +## 11. Tear down + +Deploy bills you while resources exist. Remove them when done. `--yes` confirms that deploy deletes +the stack, since the project then declares nothing to deploy; without it, deploy stops and asks you +to re-run with `--yes`. + +First keep the runtime ID from the stack outputs, because the outputs go with the stack: + +``` +RUNTIME_ID=$(aws cloudformation describe-stacks --stack-name "AgentCore-$PROJECT-default" --query "Stacks[0].Outputs[?ExportName=='AgentCore-$PROJECT-default-agent-RuntimeId'].OutputValue" --output text) +echo "$RUNTIME_ID" +``` + +Then remove the resources and the stack: ``` bun run "$CLI" remove all --yes -bun run "$CLI" deploy +bun run "$CLI" deploy --yes ``` +These outlive the stack. Delete them too: + +- The API key credential provider of step 4's `github` credential, `_default_github`: + + ``` + bun run "$CLI" identity api-key-credential-provider delete --name "${PROJECT}_default_github" + ``` + +- The log group of the Runtime, `/aws/bedrock-agentcore/runtimes/-DEFAULT`. AgentCore + Runtime makes it, not the stack: + + ``` + aws logs delete-log-group --log-group-name "/aws/bedrock-agentcore/runtimes/$RUNTIME_ID-DEFAULT" + ``` + +- The log group from step 10, if you made one: + + ``` + aws logs delete-log-group --region "$REGION" --log-group-name "/aws/box/$PROJECT" + ``` + ## Troubleshooting +- **Dev says `'box' was not found on your PATH`.** Download the build for your machine from the + box release, unpack it into a folder, add that folder to your `PATH`, then retry. +- **Dev or build says Box `cannot print the profile ... as JSON`.** The `box` on your `PATH` is + older than `0.1.11-linux-preview.7`. Install that release or later. +- **Box says `box's own packs were not found; set BOX_RESOURCES`.** A stale `BOX_RESOURCES` is + set. Run `unset BOX_RESOURCES`, or open a new terminal. +- **Dev starts but model calls fail with `ExpiredTokenException`.** Your `[default]` credentials + expired. Refresh them and restart dev. +- **Dev warns that the box profile `reads GITHUB_TOKEN for [egress.github], but it is not set`, and + box then stops with `credential variable GITHUB_TOKEN is not set`.** Dev reads each `env://` key + of the profile from the shell it runs in, then from `agentcore/.env.local`. Export it in that + shell (`export GITHUB_TOKEN=...`), set it on the same line as dev, or put it in + `agentcore/.env.local`, then restart dev. A variable set without `export` does not reach dev. +- **Dev on macOS fails with `sandbox initialization failed: Operation not permitted`.** Dev is + running inside another sandbox. Run it from a normal terminal. +- **Build says Box is not installed or not on PATH.** Install `box` and put it on your `PATH`, + then build again. +- **Build says Box refused the profile.** The lines under it are box's own error. A fresh + checkout often has no agent venv yet, and box then names `.venv/bin/python` under a write + grant. The error then says to run `uv sync` in the agent's folder (`app/`). - **Build cannot download box.** The error names the release URL. Check your network; a 404 means the pinned version is not published in `mquang-amazon/box-releases`. - **`create` fails with `ENOENT while resolving package '@opentelemetry/core'`.** The CLI's @@ -266,7 +607,7 @@ bun run "$CLI" deploy the CLI checkout (see "Install the CLI's dependencies"). - **Build says it cannot resolve credential "github" before its first deployment.** Expected when step 4's egress credential has never been deployed. Run `agentcore deploy` instead; it - provisions the credential and builds. Standalone `build` works after that. See step 6. + provisions the credential and builds. Standalone `build` works after that. See step 7. - **Deploy says a credential has no secret.** The credential's value did not reach `agentcore/.env.local`. Export `GITHUB_TOKEN` and run build again, or set `AGENTCORE_CREDENTIAL_GITHUB` in the deploy environment. From eb333e858e58159ac06b7c5575ec495dc5070a52 Mon Sep 17 00:00:00 2001 From: Varun Gunda Date: Fri, 20 Nov 2026 12:31:11 -0800 Subject: [PATCH 2/2] docs(box): Fix the local test guide where review found it differs from box-integration - box --version: give the pinned version and the minimum in one sentence. - A box/ pack: box refuses it; build no longer stops with a hint. - Warnings: list the additionalPolicies .json file warning again. - Dev: it stops only on a runtime with box.version, not on start.py or a Dockerfile. - CodeZip dev: box run starts in app/. - Gateway logs: enableApplicationLogs (written by create and add runtime), enableTraces, and L3 #470. - Prerequisites: the L3 must have #470. --- docs/box-local-testing.md | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index bfe6ef298..adf6f7c22 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -37,7 +37,10 @@ to it. ## Prerequisites -- A local checkout of the CLI and of `@aws/agentcore-cdk`. +- A local checkout of the CLI and of `@aws/agentcore-cdk`. The L3 checkout must have + [aws/agentcore-l3-cdk-constructs#470](https://github.com/aws/agentcore-l3-cdk-constructs/pull/470), + as its `box-integration` branch does. The Box gateway that `create` writes has + `enableApplicationLogs`, and an older L3 refuses it at synth with a `ConfigValidationError`. - `box` `0.1.11-preview.10` on your `PATH`, the release the CLI pins. The oldest box that works is `0.1.11-linux-preview.7`, the first release with [strands-agents/staging-boxy#625](https://github.com/strands-agents/staging-boxy/pull/625), which @@ -100,9 +103,9 @@ box --version - `which box` must name the folder you unpacked into. An older `box` earlier on your `PATH` (a source build, or Box Core's `box` in `/usr/local/bin`) wins otherwise. -- `box --version` must print `box 0.1.11-preview.10`, the release the CLI pins in - `src/core/project/backends/boxRelease.json`. The oldest box that build, deploy and dev accept is - `0.1.11-linux-preview.7`. +- `box --version` should print the pinned `box 0.1.11-preview.10` (from + `src/core/project/backends/boxRelease.json`). Build, deploy and dev accept + `0.1.11-linux-preview.7` or later. - On macOS, if Gatekeeper refuses to run `box`, clear the download flag with `xattr -dr com.apple.quarantine "$HOME/.local/share/box/0.1.11-preview.10"`. @@ -201,8 +204,7 @@ build context, and write a copy of the profile, the generated packs, and the pol `.box//aws/` for you to read. Box `0.1.11-linux-preview.7` names its packs `@box/base`, `@box/bedrock`, and `@box/agentcore`. -For a profile that names a pack or a plugin `box/`, build stops and gives each `@box/` -name. +A profile that names a pack `box/` fails: box refuses it and names the `@box/` pack. - **Gateway targets.** Each host or `host:port` that an `[egress]` entry, an `[mcp]` server with `type = "http"`, or a policy permit names, and that the policy allows at least one @@ -222,7 +224,9 @@ name. `[egress.github]`. Nothing is written. - **Warnings.** Build warns when Box enforces rules that the gateway does not (a path, method, or forbid), when an entry's host gets no target, and when a target is signed for an - AWS service that no policy of the gateway's role grants. + AWS service that no policy of the gateway's role grants. It also warns for a `.json` file in + the gateway's `additionalPolicies` that does not exist, cannot be read, or is not a JSON + object, as it counts none of its actions. - **The AgentCore Runtime profile.** Build derives `.box-dist/profile.toml` from the local profile. Each key of the local profile stays, and build changes only what must differ on AgentCore Runtime: @@ -286,8 +290,8 @@ deploy. It deploys nothing. The agent signs its Bedrock calls with your `[defaul Dev runs an agent in a box only in a Box project, as build and deploy do: `agentcore.json` must have `"projectType": "box"`, which `create` writes for the box templates. Without it, dev runs a -plain runtime the usual way, and stops on one that starts box (a CodeZip `start.py` entrypoint, or -a Dockerfile that installs box) with `agentcore.json has no "projectType": "box"`. +runtime the usual way, and stops on one that has `box.version` with +`agentcore.json has no "projectType": "box"`. ### Which box builds exist @@ -363,8 +367,9 @@ bun run "$CLI" invoke --local --runtime agent --payload '{"prompt":"What is 17 t **CodeZip template** (`agent-python-strands-box`; create it in step 3 with `--template agent-python-strands-box`): -- Dev runs `box run .box//local/profile.toml` in the project folder with the `box` on - your `PATH`. The box listens on 8080 and relays to the agent on 8081. +- Dev runs `box run` on `.box//local/profile.toml` from the agent's folder + (`app/`), with the `box` on your `PATH`. The box listens on 8080 and relays to the agent + on 8081. - Invoke once the dev output shows `Uvicorn running on http://127.0.0.1:8081`. - Dev needs the agent's venv: `create` runs `uv sync` in `app/agent`, on a uv-managed Python in `~/.local/share/uv/python`, the only Python folder the profile lets box run. With @@ -476,9 +481,14 @@ bun run "$CLI" logs runtime --name agent --since 15m --query '"strands.box.polic Each record is one decision, with `strands.box.policy.verdict`, `.rule`, and `.resource`. To show only the deny decisions, use `--query '"deny"'`. -Deploy always sends the `APPLICATION_LOGS` of each Box gateway to -`/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/`. The gateway sends no -traces to X-Ray. Read the gateway logs with the gateway ID from step 9: +A Box gateway that `create` or `add runtime` writes has `"enableApplicationLogs": true` in +`agentcore.json`, and they tell you so with a notice. Deploy then sends the gateway's +`APPLICATION_LOGS` to `/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/`. +This needs an L3 that has +[aws/agentcore-l3-cdk-constructs#470](https://github.com/aws/agentcore-l3-cdk-constructs/pull/470), +as the `box-integration` branch of the L3 does. Set `"enableApplicationLogs": false` to stop the +logs. Traces to X-Ray stay off unless you set `"enableTraces": true`, which needs CloudWatch +Transaction Search in the account and Region. Read the gateway logs with the gateway ID from step 9: ```sh aws logs tail "/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/$GATEWAY_ID" --since 15m