Skip to content

feat(box): Derive the AgentCore Runtime box profile from the local box profile of each runtime - #2866

Merged
SaiAbhishek98 merged 53 commits into
aws:box-integrationfrom
SaiAbhishek98:sa-5/box-profile-per-agent-v5
Nov 20, 2026
Merged

SaiAbhishek98 merged 53 commits into
aws:box-integrationfrom
SaiAbhishek98:sa-5/box-profile-per-agent-v5

Conversation

@SaiAbhishek98

@SaiAbhishek98 SaiAbhishek98 commented Nov 20, 2026 •

Copy link
Copy Markdown

Description

Problem

aws/agentcore-cli#2859 gives each runtime of a
Box project its own local box profile, .box/<runtime>/local/profile.toml. agentcore dev runs
that profile. Build and deploy did not use it for AgentCore Runtime. renderRuntimeBoxProfile made
the Runtime profile from agentcore.json and from the Box network model. Thus:

  • Each stdio [mcp.<name>] server and each [tool.<name>] of the local profile was not on
    AgentCore Runtime, and build gave no message.
  • Each key that the renderer did not know was not on AgentCore Runtime. For example, a variable
    in [agent.env] or a grant in [agent.filesystem] that the user added.
  • Build removed each [telemetry.<name>] target that is not CloudWatch, and gave no message.

The derived profile also needs these changes on AgentCore Runtime:

  • A box with no cloudwatch_logs target sent its records to no log group.
  • start.py gave box the Runtime Python as python3. box refuses a stdio server whose program has
    the name of one of its interpreter aliases (python, python3).
  • box 0.1.11-linux-preview.7 names the packs that it ships @box/<name>. The CLI wrote
    box/<name>. box 0.1.11-linux-preview.6, the pin, refused the @box/ names and the key input
    that the default log target reads.
  • A CodeZip agent needed the ffi shim, because Box Core refused executable memory on Linux. The
    user selected box 0.1.11-mquang.preview.9, which allows it (decision 18).

Solution

Build derives the Runtime profile from the local profile of the runtime. Each key of the local
profile goes to the Runtime profile. Build changes a value only when the value must be different
on AgentCore Runtime. When a value cannot operate on AgentCore Runtime and build has no mapping for
it, build stops, and the message gives the key and its file:line:column. When the Runtime can
operate with no value there, build leaves the value out and gives a warning. This is the decision
of the user: "add stuff that we need for running it on runtime but everything else needs to be the
same".

deriveRuntimeProfile(local, context) (src/core/project/runtimeProfile/) runs 4 rules in this
sequence:

  1. refusals reads the local profile as the user wrote it, and gives a problem for each key that
    cannot operate on AgentCore Runtime. Build stops for each problem.
  2. gateway gives each passthrough target of the Box gateway of the runtime one route to
    ${{ inputs.gateway.url }}/<target>.
  3. additions adds what is necessary only on AgentCore Runtime, and gives each value of the template its
    Runtime value.
  4. paths moves each path of the project and of the home folder to its position on AgentCore
    Runtime.

buildBoxNetwork keeps the derived profile in BoxNetwork.runtimeProfile, and the runtime profile
writer stages it. This PR removes renderRuntimeBoxProfile and the Runtime part of
renderBoxProfile. renderBoxProfile writes only the local profile.

Before the PR removed the renderer, a test recorded the output of the renderer of box-integration
into runtimeProfile/__fixtures__/old-renderer-tables.json. The template part of the fixture is
recorded again from the renderer of #2867 at
f40ebce7:
box-integration at 7252504c with the @box/ pack names and no ffi shim. Only
AGENTCORE_RUNTIME_URL of the A2A template and the PYTHONPATH of each CodeZip template changed. For each box template, the derived
profile is equal to that output. Only the sequence of the keys, the name of the route of the first
host of an entry (decision 5), the port of the first ingress (decision 6), and the default log target
are different.

The branch has merges of box-integration at 7252504c
(aws/agentcore-cli#2862) and at b8055125
(aws/agentcore-cli#2865), not rebases, so each
commit that a reviewer read stays the same.

Commits

Commit What it does
35f0ffaf Stop for .box/profile.toml; the local profile name <project>-<runtime>; a stop for an API key credential that two runtimes give different values; the guide and the Dockerfile comment name .box/<runtime>/local/
4a1e720e Stop build for a box runtime that has no local profile
b60ff0f9 to 7a1e4da5 The derivation and its 4 rules. In these commits, build does not use them
c6dc336e The default log target: the log group of the runtime
a3ee1f1c The rules get the changes of aws/agentcore-cli#2857
bab52a94 Build stages the derived profile, and the earlier renderer goes
92649771 start.py exports a Python name that box does not alias
04f6bccb The packs that box ships have @box/ names; build stops for an earlier box/ name
6c53232e Pin box 0.1.11-linux-preview.7
eb30924b Tests of two routes of one profile to one host
08f7334c Stop build for a write grant in the code folder of a CodeZip runtime
ac3a9d53 The start.py test writes no bytecode into src/assets
737e1079 The route of an entry with one host has the name of the entry
398299fc Stop build for a host home path and for an [agent] program that a CodeZip Runtime does not have
2913cd26 The Runtime gets no template grant that the local profile removed
e43ee627 A telemetry table with no kind that adds to a CloudWatch target of a pack
42832149 The guide says where build stages the profile, and lists each stop

After the approval at
3ba0bb6e, one batch of new commits:

Commit What it does
4d165cd9 Stop build for a CloudWatch target that box refuses, and copy only the targets that box takes
afe56a6e Four comments and one message say what the code does
797ed4bf One isTable and one RUNTIME_AWS_SIGNER for the rules
5d2eb4af The start.py tests skip on Windows
981588ab The notice of the default log target, and DISABLE_ADOT_OBSERVABILITY turns it off
dc1938e1 No Runtime route to a target that build does not write
086bc462 The grants that only the Runtime has stay when the user removed a grant of the template
bbc64303 The region of the Runtime replaces a region of the user, and AWS_PROFILE goes
aa1e11c5 Build stops only for a key that cannot operate on the Runtime, and warns for the others
5595c28e Remove the stop for .box/profile.toml of the earlier layout
797024a2 A deny entry on the venv goes, with a warning
cbd378c3 The README says what a Box project holds after #2859
a4f44a13 Remove dead fields, exports, and copies
fa622c81 The code folder stays in the Runtime PYTHONPATH of the agent and of each leaf
96c321c9 Merge box-integration at 7252504c: the start folder, staged_policies, and the A2A Runtime URL go into the rules
77d250e1 start.py tests for both ways to read policies, and policies on one line
664e074c The first ingress listens on the port of the protocol
07449584 The route of the first host of an entry has the name of the entry
0a00f77f The guide gives each change, stop, and warning of the derivation

After the review of Leo at 0a00f77f:

Commit What it does
9637a938 BOX_MINIMUM_VERSION, BOX_RELEASE_PAGE, and the hint for a box before preview.7, from #2867
6ce73631 No ffi shim: the shim removal of #2867, and no shim in the derivation
853a8a56 Pin box 0.1.11-mquang.preview.9, and a hint for a machine with no build in it
71864dd2 The write of agentcore.json fails for each user, root too, in the notice test
5172252f The doc of assertNotBoxProject is on its function
cc139a75 No workload_port warning for a value that the user did not set
ed0e4b03 The route name from the first host of the entry that has a target
f9227970 The [mcp] test of the writer, and the doc of BoxNetwork.runtimeProfile
9fb98f98 Merge box-integration at b8055125 (#2865)
eb8685bd No path-model case for a profile of the earlier layout
d6330f6d The staging test examines that .box-dist has no ffi folder

Decisions

Each item is a decision that a reviewer can examine. "User" is a decision of the user, "Rule" is a
fact or a decision from the rule work, and "PR" is a decision of this PR that the user can reverse.
The numbers stay the same as in the earlier versions of this description.

The derivation

  1. (User) The Runtime profile comes from the local profile. Build adds only what is necessary on
    AgentCore Runtime, and keeps each other key, the packs of the user included.

  2. (Rule) The paths on a CodeZip runtime: the venv Python goes to ${{ inputs.python.path }}, the
    venv and the code folder go to ${{ inputs.code.dir }}, and ${{ home }}/.local/share/uv/python
    goes to ${{ inputs.python.prefix }}. agentcore dev starts box in the code folder of a
    CodeZip runtime (boxStartFolder reads build and codeLocation from agentcore.json, since
    test(e2e): Deploy and invoke every Strands Box template #2865), so the local profile names the code folder ${{ workspace }}. A Box
    project is only for new projects, so the derivation has no condition for a profile of the
    earlier layout. A container runtime keeps each path, because agentcore dev runs the profile
    in the image that deploy builds. A different absolute path, for example /etc/ssl/certs, stays:
    build cannot see the file system of the Runtime.

  3. (Rule, PR) Build stops, and does not guess, for each of these:

    • network.contain_egress = false on [agent], a stdio server, or a tool
      (RUNTIME_EGRESS_NOT_CONTAINED). Its calls do not go through the Box gateway there.
    • A [telemetry.<name>] target that is not cloudwatch_logs, cloudwatch_traces, or file
      (RUNTIME_TELEMETRY_NOT_CLOUDWATCH). A CloudWatch target that box refuses when a run starts
      (RUNTIME_TELEMETRY_REFUSED). A table with no kind that adds to a CloudWatch target of a
      pack is not a problem.
    • CodeZip: in a required grant, a command word, or a program, a path of the project that is not
      in the code folder, a path in the venv, or a path in the home folder: ${{ home }}, ~,
      /Users/..., or /home/... (RUNTIME_PATH_NOT_FOUND). Build examines each part of a : list
      and the value of each --flag=, and nothing else in a word.
    • CodeZip: an [agent], stdio server, or tool program that PATH finds, for example npx
      (RUNTIME_PROGRAM_NOT_FOUND). The command of the template moves to the Runtime Python.
    • CodeZip: a write or write_file grant in the code folder (RUNTIME_WRITE_IN_CODE). On the
      Runtime the agent can run each file in that folder, and box refuses a write grant there.

    Build warns, and goes on, for each of these:

    • A deny or deny_write entry, or an optional grant, that has no position on the Runtime. It goes.
    • A deny entry on the venv or in it. It goes, because the venv is the code folder on the
      Runtime, and a deny there denies the code of the agent.
    • A file telemetry target. It goes, because nobody can read the file on the Runtime.
    • A program at an absolute path of the system, for example /opt/homebrew/bin/python3. It stays.
      Build cannot see the image of the Runtime, and box stops the run when the program is not there.

    The user can change each stop to a warning, if the user selects that.

  4. (Rule) The gateway rule:

    • Each host of an [egress.<name>] entry with a gateway target gets a route with one backend to
      its target, a bare aws:// signer, and ${{ inputs.aws.region }}
      (d6eec45d).
      The secret goes, because the gateway target sends the credential. The other keys stay.
    • An HTTP [mcp.<name>] keeps its name and its other keys. It keeps only an env:// secret,
      with no inject.
    • A passthrough target that no entry names (bedrock, agentcore, a host that only a permit
      names) gets a route.
    • Two passthrough targets for one host stop build.
    • When the policy denies each host of an entry, the entry goes, and the Box network model warns
      for it. An entry that the model rejects goes, and the model gives the one problem for it.
    • (PR) The runtime profile writer stages no route to the target of a host when agentcore.json
      has no credential for its API key. The gateway targets writer writes no such target, so the
      route has no target on the Runtime.
  5. (PR) The route of the first host of an entry that has a target has the name of the entry, for example
    [egress.github]; its backend names the target egress-github. Each other host of the entry,
    and each target that serves no entry, gets a route with the name of its target. The derived
    profile keeps the packs, so a pack such as @box/anthropic adds its own [egress.anthropic] on
    the Runtime. box 0.1.11-linux-preview.7 refuses a profile with that entry and a route to the same
    host with a different name, and accepts the route with the name anthropic: box merges the table
    of the pack with it. A pack entry with two hosts has the same collision on each host after the
    first. No pack that box ships has an entry with two hosts.

  6. (Rule) The additions rule:

    • packs: the packs of the user in their sequence, then @box/agentcore, and
      @box/agentcore-codezip for CodeZip, each one time.
    • [profile] name: the name of the project, because each microVM runs one profile.
    • [options] bedrock.region: the build region.
    • [agent]: a value of the template gets its Runtime value. LOCAL_DEV, --reload, and
      --reload-dir go. The 2 AWS stand-in keys and, for CodeZip, the ffi shim at the start of
      PYTHONPATH come in. Each value of the user stays, but these change (PR):
    • [[agent.ingress]] (PR): the first ingress listens on 0.0.0.0:<port of the protocol>,
      because the Runtime sends the requests only to that port. Its workload_port is the one of the
      template when the agent keeps the command and the port variable of the template. Else it is the
      workload_port of the user, with a warning when the user set it. This is the opposite of an
      earlier version, which kept a listen port that the user changed. Each other ingress of the user listens on 0.0.0.0.
    • [agent.filesystem] (PR): a Runtime grant of the template does not come in when the user
      removed its local grant. A grant that only the Runtime has always comes in: /usr/lib64, /lib64,
      and exec on the code folder, which contains the dependencies and their native modules on the
      Runtime.
    • [tool.<name>]: a table that the template writes, as the template writes it, gets the Runtime
      table of the template. The Runtime template has none, so the [tool.uname] of
      3df66a24
      goes: it protects the local venv, and the Runtime has no venv. [project] stays, the same as
      the earlier renderer wrote it.
    • [telemetry]: each CloudWatch target that box takes gets a bare aws:// signer, in the
      deploy region when it names none.
    • (PR) An [agent] with no PYTHONPATH gets ${{ inputs.code.dir }}, and the paths rule keeps
      ${{ inputs.code.dir }} at the end of the PYTHONPATH of the agent and of each leaf that the
      Runtime Python runs, one time. No PYTHONPATH names an ffi shim.
  7. (Rule) The memory inputs: the @box/agentcore pack is for the project, so the pack of each
    runtime declares the input of each memory of the project. This has no effect: the L3 binds each
    memory to each runtime
    (AgentCoreApplication.bindResources),
    so each runtime has each MEMORY_<NAME>_ID.

  8. (PR) The default log target. When the derived profile has no cloudwatch_logs target, build adds
    [telemetry.agentcore]: box sends its deny, permit, and trace records to the log group of the
    runtime, /aws/bedrock-agentcore/runtimes/<runtime ID>-DEFAULT, log stream otel-rt-logs. box
    reads the two names from OTEL_EXPORTER_OTLP_LOGS_HEADERS when the run starts, and does not start
    when the Runtime does not set it.

    • agentcore create and agentcore add runtime give a notice after they write agentcore.json.
      The notice says what box sends, where, which retention applies, that the log group stays after
      the runtime goes, and that CloudWatch Logs charges for the records.
    • DISABLE_ADOT_OBSERVABILITY = "true" in the envVars of the runtime turns the target off.
      instrumentation.enableOtel is not the switch, because each box template of
      feat(dev): Hand box run the profile's env:// keys instead of copying them to .env.local #2862 writes it false.
    • No IAM change: the Runtime construct gives the execution role logs:CreateLogStream and
      logs:PutLogEvents on /aws/bedrock-agentcore/runtimes/*
      (aws-cdk runtime.ts).
      The CDK stack does not make the -DEFAULT log group; the Runtime makes it.
    • box reads a key of a list input only with
      strands-agents/staging-boxy#625,
      which is in 0.1.11-linux-preview.7.
    • Tests: "the default CloudWatch Logs target" in additions.test.ts, and the notice tests in
      manager.test.ts and manager.box.test.ts.

The local profiles

  1. (PR) The [profile] name of a local profile is <project>-<runtime>. box keeps one profile of
    each name on a machine, so after dev runs one runtime, box refused the profile of each other
    runtime with the same name. The Runtime profile keeps the name of the project.
  2. (Removed) An earlier version stopped build, deploy, and dev for .box/profile.toml of the
    earlier layout. The review of feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859 selected no hint for that layout, so
    5595c28e
    removes the stop.
  3. (PR) Build and deploy stop for a box runtime with no local profile, and name the file to make.
    feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859 resolves no profile for it, and then there is nothing to derive from.
  4. (PR) Build and deploy stop when two runtimes give one API key credential (the name of an
    [egress] entry) two different env:// variables. One credential holds one key, so the gateway
    target of the second runtime can send the key of the first.

Duplicate routes to one host (each one pinned by a test)

  1. Two [egress] entries that name one host stop build with one EGRESS_DESTINATION_OVERLAP
    problem that names the two entries. This applies to two open routes, and to a route with a
    secret and an open route. box itself refuses two routes with a secret to one host.
  2. One entry that names its host two times, as api.example.com and api.example.com:443, gets
    one target and one route.
  3. The additions rule adds @box/agentcore and @box/agentcore-codezip only when the profile
    does not have them, and adds the ffi shim to PYTHONPATH only when PYTHONPATH does not start
    with it.

Box

  1. (PR) start.py exports BOX_PYTHON as the versioned file in the folder of sys.executable
    (python3.12), else the file that sys.executable links to, else sys.executable. It keeps
    staged_policies of feat(dev): Hand box run the profile's env:// keys instead of copying them to .env.local #2862: with no tomllib and no tomli, it reads
    policies as a JSON list on one line. The derived profile writes policies on one line.
  2. (PR) The packs that box ships have @box/ names. Build stops, before box runs, for a profile
    that names a pack or plugin by its earlier box/<name> name, and the message gives each new name.
    Build does not change the profile of the user. This is the breaking change of this PR.
  3. (User, PR) The pin is box
    0.1.11-mquang.preview.9:
    staging-boxy b0846169 with
    strands-agents/staging-boxy#549, on Box
    Core 78e752b0 with strands-agents/box#488. It
    does not have fix(credentials): do not sign the headers that botocore does not sign strands-agents/box#537.

Scope

  1. The add runtime box runtime, its Box gateway, start.py, the empty .venv, the rollback,
    the refusal of a TypeScript runtime, and the .box/<runtime>/aws/ cleanup of remove runtime
    are in feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859. An earlier version of this PR had its own version of these. This
    PR does not have them. It also does not box an exported harness or a Bedrock Agent import:
    feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859 refuses them in a Box project.
  2. The two identifierOf items from the review of Leo on
    aws/agentcore-cli#2860 are in
    feat(gateway): Accept enableApplicationLogs and enableTraces, send the logs of a new Box gateway, and find the target ids of two Box gateways #2860, not here. This PR does not touch ensureBoxGateway: box-integration
    does not have it after feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859, and this PR does not add it again. So
    feat(gateway): Accept enableApplicationLogs and enableTraces, send the logs of a new Box gateway, and find the target ids of two Box gateways #2860 and this PR do not touch the same lines there.
  3. Follow-up, from the review of Leo on feat(gateway): Accept enableApplicationLogs and enableTraces, send the logs of a new Box gateway, and find the target ids of two Box gateways #2860: addBoxRuntime (manager.tsx)
    must yield the Box gateway logs notice (boxGatewayLogsWarnings) after addResource writes
    agentcore.json, the same as create, so that it prints a notice only for a gateway that it
    wrote. feat(gateway): Accept enableApplicationLogs and enableTraces, send the logs of a new Box gateway, and find the target ids of two Box gateways #2860 is not merged, so this PR does not have that change. The
    default log target notice of this PR comes after the write.
  4. This PR changes the paragraph of README.md on Box: the seven box templates, a box profile for
    each runtime, what add runtime and export harness do in a Box project, and the derivation.
  5. aws/agentcore-cli#2867 also pins preview.9 and
    removes the shim. The files that they share are the same in the two PRs. If
    fix(box): Ship only the pinned box, and drop the old box/<name> pack-name stop #2867 merges second, it keeps refuseOldShippedNames (decision 17) and
    BOX_OTHER_MACHINE_HINT, and drops its changes to renderRuntimeBoxProfile, which this PR
    removes. If this PR merges second, it gets the boxReleaseFor of fix(box): Ship only the pinned box, and drop the old box/<name> pack-name stop #2867, which
    accepts only the pinned box.

Independent review

A reviewer with no context read 1405932a..3ba0bb6e. This PR fixes these items:

  • The pack collision of decision 5.
  • An [agent] program of the user, and ~, /Users, and /home paths, that a CodeZip Runtime
    does not have: decision 3.
  • The Runtime grants of the template that the agent always got, also with no local filesystem
    table: decision 6.
  • A telemetry table with no kind, and 2 comments that were not correct.

A second review read 3ba0bb6e before the batch. The batch fixes these items:

  • The default log target had no notice and no switch to turn it off: decision 8.
  • A route to a target that build does not write : decision 4.
  • A Runtime-only grant that went with a grant of the template, a region of the user, AWS_PROFILE,
    a deny or optional grant with no position, a file target, and a system program: decisions 3 and 6.
  • The README and the comments of the manager that were not correct after feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859, and
    a guide note on [project] access = "write" and a stdio server on the venv Python.
  • Not changed: a notice for an imported executionRoleArn. The user made the decision that the role of
    the customer is the responsibility of the customer.

These stay as they are:

  • A key that a pack adds (a tool program, a path, a non-CloudWatch telemetry target) is not
    examined: the rules read only the text of the local profile. box skips a pack tool when its program
    is not there (the Linux check shows this for uname). A third-party pack with an HTTP MCP server
    that signs with aws:// merges its secret back adjacent to the backend, and box refuses that when the
    agent starts. No pack that box ships has an MCP server.
  • A .. segment in a path: box refuses it when it resolves the local profile, so build stops first.
  • structuredClone changes a TOML local date into a Date. No box key takes a date.
  • The key positions read a key in quotes that has a dot as a nested key, so a message can give an
    incorrect line.

Related Issue

Closes #

Documentation PR

docs/box-local-testing.md and README.md are in this PR: the paths of the layout, where build
stages the Runtime profile, each change, stop, and warning of the derivation, and the default log
target and its switch.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Other (please describe):

Testing

  • I ran bun test
  • I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not
    applicable (CI does not run them for you)
  • I ran bun run typecheck
  • I ran bun run lint:check
  • I ran bun run format:check
  • I ran bun run audit
  • I ran bun run secrets:check
  • I ran bun run build
  • If I modified src/assets/, I updated affected snapshots with
    bun test <test-file> --update-snapshots and committed them
  • If I re-recorded fixtures or golden files, every change beyond account identifiers is
    explained by this PR
  • This PR does not change command.md (the release workflow regenerates it)

Gates. The base is box-integration at
b8055125.

base b805512 this PR (d6330f6)
bun test 5528 pass, 7 skip, 0 fail (5535 tests, 347 files) 5791 pass, 7 skip, 0 fail (5798 tests, 353 files)
typecheck, lint:check, format:check, secrets:check, build, audit pass pass

bun.lock does not change. All of manager.box.test.ts also passes as root (uid 0) in a Linux container
(python:3.12-slim-trixie, bun 1.4.0): "a failed write of agentcore.json gives no notice of the
default log target" passes there. It did not pass on the verify / Linux runner at 0a00f77f.

Tests that fail when the code breaks. At the head, a script made each of these 19 changes, one at
a time, ran the tests for it, and put the file back. Each change made one or more tests fail:

  • the pin goes back to box 0.1.11-linux-preview.6; the asset names a different version; the SHA-256 is
    not 64 hex digits;
  • BOX_INSTALL_HINT or the resolver hint names only the pinned release; no hint for a box before
    preview.7;
  • the agent gets the ffi shim again; an agent with no PYTHONPATH gets none; a leaf gets the shim
    first again; the code folder goes from PYTHONPATH; the zip stages an ffi folder;
  • add runtime gives the notice before the write of agentcore.json; add runtime hides the write
    error;
  • a workload_port warning for a value that the user did not set; the route name takes a first host
    with no target; the writer removes only [egress] routes;
  • the code folder is the one of the earlier layout; dev starts a CodeZip box in the project root.

Before this batch, 38 changes at 0a00f77f, 26 before the approval, 16 of the gateway rule, and 29
of the additions rule gave the same result.

Real check, with no AWS access (a local script, not in this PR), at the head. It runs the CLI
from source on a scratch project with env -i, empty AWS files, and a network guard: agentcore create, agentcore add runtime --name helper --language python, then the code of the first runtime
in the second. It adds to each local profile an [egress] entry with an env:// key, a policy file,
a CloudWatch Logs target, and a tool that the venv Python runs from the code folder. It adds to the
first profile an HTTP MCP server, and a stdio MCP server when the first runtime is CodeZip. Then
agentcore build runs to CDK synth. It ran for agent-python-strands-box (two CodeZip runtimes)
and for agent-python-strands-box-container (a container runtime and a CodeZip runtime). For each
runtime, box profile show --format json --full of the staged Runtime profile, with dummy inputs,
gave no error:

  • with the published macOS box 0.1.11-linux-preview.7 (SHA-256
    1ad9676124c9878123b45da05332fcff30504a07f04d443284bd676836cd9aff), in the project layout and in
    the layout that start.py makes, with the BOX_PYTHON that start.py computes;
  • with the published Linux box 0.1.11-mquang.preview.9 (SHA-256
    5b0f8802fb1c5cbc22db4bfcefc9061e048e931c972584350ebce6c1b15da884, the same as the box that build
    staged) in finch, --network none, public.ecr.aws/amazonlinux/amazonlinux:2023.

No staged .box-dist has an ffi folder, and no Runtime profile names .box-dist/ffi. The stdio
server and the tool are in the resolved box.toml on macOS and on Linux. The only table of a local
profile that the Runtime profile does not have is the [tool.uname] of the template (decision 6).
create and add runtime each gave the notice of the default log target. The network guard
refused nothing for the CodeZip project. For the container project it refused a uv lock that build
runs, and build went on to CDK synth.

No test for these:

Checklist

  • I have read the CONTRIBUTING document
  • I have added any necessary tests that prove my fix is effective or my feature works
  • I have updated the documentation accordingly
  • I have added an appropriate example to the documentation to outline the feature, or no new
    docs are needed
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this
contribution, under the terms of your choice.

Sai Abhishek and others added 22 commits November 19, 2026 18:43
…e the name of its runtime

[aws#2859](aws#2859)
([1405932](aws@1405932))
keeps a box profile for each runtime in .box/<runtime>/{local,aws}.
This commit is a cherry-pick of
[1fbbc90](1fbbc90),
which makes the same layout. It keeps only what 1fbbc90 does and
commit keeps the words of aws#2859.

The problems that aws#2859 does not stop:

- Each local profile has the name of the project, and box keeps one
  profile of each name on a machine. Thus, after dev runs one runtime,
  box refuses the profile of each other runtime.
- No command reads .box/profile.toml, the one profile of the earlier
  layout. Build and deploy give a runtime with no
  .box/<runtime>/local/profile.toml an empty profile, and say nothing
  about the old file.
- An API key credential has the name of its [egress] entry. Two
  runtimes can thus give one credential two different env:// values.
  Then the gateway target of the second runtime sends the key of the
  first runtime.
- docs/box-local-testing.md and the Dockerfile of the box container
  template name .box/profile.toml.

What this commit adds:

- The [profile] name of a local profile is <project>-<runtime>
  (boxLocalProfileName). The AgentCore Runtime profile keeps the name
  of the project, because each microVM runs one profile.
- When a project has .box/profile.toml, build, deploy, and dev of a box
  runtime stop (assertNoProjectBoxProfile). The message tells the user
  to move the profile and its policy files into .box/<runtime>/local/.
  The CLI does not move the file.
- Build and deploy stop for an [egress] entry when an earlier box
  runtime uses its API key credential for a different env:// variable
  (API_KEY_CREDENTIAL_SHARED, in readBoxNetworks).
- The guide and the Dockerfile comment name .box/<runtime>/local/.

box limits the length of a profile name, and a long HOME makes the limit
less. With a HOME of 45 characters, box refused pr5demo-second (14
characters) and ran p5-second (9 characters).

Tests: boxNetworkSource.test.ts "refuses a project that keeps
.box/profile.toml, and runs no box" and "refuses an entry whose API key
credential another runtime takes for another variable". box.test.ts
"refuses a box runtime in a project that keeps .box/profile.toml" (two
tests). container.test.ts "refuses a project that keeps
.box/profile.toml, and stages nothing". boxProfile.test.ts "names itself
after the project and the runtime". For each of these, a change that
removes the check, or that names the profile after the project only,
causes an error in its test. The commit also adds tests for two
runtimes: each one reads, stages, and runs only its own profile
(box.test.ts, container.test.ts, boxEnvLocal.test.ts,
boxCodeZip.test.ts, boxContainer.test.ts, and boxNetworkSource.test.ts
"reads each runtime's own local box profile and policy files, one after
the other"). The tests of aws#2859 do not change.

Co-authored-by: Varun Gunda <vvargu@amazon.com>
Build and deploy derive the AgentCore Runtime profile of each box
runtime from its .box/<runtime>/local/profile.toml. When that file is
not there, readBoxNetworks resolves no profile, and build has nothing
to derive from. Then the runtime profile writer stops with a message
that names no missing file.

With this change, build and deploy stop before they run box for a box
runtime with no local profile. The message names the profile to create
for each runtime: "runtime "<name>" runs its agent in a box (it has
box.version in agentcore.json), but .box/<name>/local/profile.toml does
not exist. Create that box profile for the runtime, or remove its
box.version, then retry." This part of the earlier local commit
a094c5eb (branch sa-5/box-profile-per-agent-v4, worktree
/Volumes/workplace/box-v3/agentcore-cli-pr5v4) stays. The rest of that
commit, the box runtime that add runtime makes, is now in
[aws#2859](aws#2859).

Tests: boxNetworkSource.test.ts "stops for a box runtime with no box
profile of its own, and names the profile to create". The test "reads
each runtime's own local box profile and policy files, one after the
other" gives its third runtime a profile.
…he local profile

Build makes the AgentCore Runtime profile from agentcore.json and from
the Box network model. It does not read the local profile of the
runtime. Thus a key of the local profile that build does not know is
not on AgentCore Runtime, and build gives no message. For example, the
Runtime profile has no stdio [mcp] server.

This commit adds the frame of the fix, src/core/project/runtimeProfile/.
It does not change the output of build.

- deriveRuntimeProfile(local, context), in derive.ts, starts from the
  local profile and runs 4 rules in this sequence: refusals, gateway,
  additions, paths. Each rule gives a new table, its problems, and its
  warnings. A problem stops build.
- types.ts has the context of a rule, the problem, and the rule. The
  context has the runtime, the region, the Box gateway and its targets,
  the hosts, the CloudWatch targets, the policy files, the paths on
  AgentCore Runtime, the template profiles, and the position of each
  key.
- context.ts makes the context: runtimePaths, runtimeTemplate, and
  profileKeyPlaces, which finds the line of each key of a profile.
- rules/refusals.ts, rules/gateway.ts, rules/additions.ts, and
  rules/paths.ts do not change a table in this commit. The comment of
  each rule tells its work, and the functions of
  templates/boxProfile.ts that it replaces.
- serialize.ts writes a profile table as TOML, with smol-toml.
- The network source keeps the text of the local profile as a TOML
  table, with the position of each key (ParsedProfile.source).
  buildBoxNetwork runs deriveRuntimeProfile on it. It adds each problem
  to the failures of the network, each warning to its warnings, and the
  profile to BoxNetwork.runtimeProfile. The runtime profile writer
  writes renderRuntimeBoxProfile, the same as before.
- FAILURE_CODES has the 3 problem codes: RUNTIME_PATH_NOT_FOUND,
  RUNTIME_PROGRAM_NOT_FOUND, and RUNTIME_EGRESS_NOT_CONTAINED.

Tests: runtimeProfile/derive.test.ts: the sequence of the rules, a key
that no rule changes stays the same for CodeZip and for a container,
the derivation changes no table that it gets, the paths, the template
profiles, the position of each key, and the TOML text.
boxNetworkSource.test.ts "derives the runtime's AgentCore Runtime
profile from the text of its own local profile". bun test: 5369 pass,
7 skip, 0 fail.
…Watch

At this time, a box on AgentCore Runtime cannot send telemetry to a
[telemetry.<name>] target that is not CloudWatch. Today,
cloudWatchTelemetry removes such a target from the Runtime profile, and
build gives no message.

This commit adds RUNTIME_TELEMETRY_NOT_CLOUDWATCH to
RUNTIME_PROFILE_PROBLEM_CODES, and thus to FAILURE_CODES. The refusals
rule of the next commit uses it. This commit does not change the output
of build.
…ofile

The Runtime profile has no stdio [mcp.<name>] server and no
[tool.<name>] table, because renderRuntimeBoxProfile makes the profile
from agentcore.json and not from the local profile. Build gives no
message for them. Build also removes each [telemetry.<name>] target that
is not CloudWatch, and gives no message.

This commit fills the first rule and the last rule of
deriveRuntimeProfile. At this time, build does not use the rules:
renderRuntimeBoxProfile writes the Runtime profile.

- rules/refusals.ts reads the local profile as the user wrote it. It
  gives a problem for each key that cannot operate on AgentCore Runtime.
  The text of each problem starts with the key, and the problem gives
  the line of the key.
  - network.contain_egress = false in [agent], in a stdio [mcp.<name>],
    or in a [tool.<name>]: RUNTIME_EGRESS_NOT_CONTAINED.
  - A [telemetry.<name>] kind that is not cloudwatch_logs or
    cloudwatch_traces: RUNTIME_TELEMETRY_NOT_CLOUDWATCH.
  - CodeZip only: a path of the project that is not in the code folder,
    a path of the home folder, or a path in the venv:
    RUNTIME_PATH_NOT_FOUND.
  - CodeZip only: a stdio server or tool program that is not the venv's
    Python or a file in the code folder: RUNTIME_PROGRAM_NOT_FOUND. A
    system program, for example /usr/bin/grep, is also a problem,
    because build cannot see the file system of the Runtime.
- rules/paths.ts is the last rule. On CodeZip, it moves the venv's
  Python to ${{ inputs.python.path }}, the venv and the code folder to
  ${{ inputs.code.dir }}, and the uv Pythons to
  ${{ inputs.python.prefix }}. It moves them in each key, but not in
  packs, policies, [profile], [egress], an HTTP [mcp.<name>], or
  [telemetry]. Each entry of a path list moves, and an entry that names
  a Runtime input stays. Then each filesystem list has one grant for
  each path. A leaf that runs the Runtime's Python gets the PYTHONPATH
  of the code folder if it sets none. If it sets a PYTHONPATH, the
  _ctypes folder goes in front, as the additions rule does for [agent].
  A container image keeps each path.
- projectPaths.ts has the path moves and the walk of the keys. The 2
  rules use them.

Each stdio [mcp.<name>] and each [tool.<name>] goes to the Runtime
profile with each key that it has, after the path moves.

The rules replace the path moves of runtimeCodeZipRunner, and the
filter in cloudWatchTelemetry that keeps only CloudWatch targets. Later
commits remove these, when build uses the rules.

Tests: rules/paths.test.ts and rules/refusals.test.ts have 36 new
tests. The test "keeps each stdio [mcp] server and each [tool], with
each key, in the Runtime profile" fails with the stub rules of the frame
commit. bun test: 5384 pass, 7 skip, 0 fail. Before this
commit: 5348 pass, 7 skip, 0 fail. Typecheck, lint, and the format check pass.
Box 0.1.11-linux-preview.6 for macOS accepts a Runtime profile with a
stdio server that starts .venv/bin/python3.15 and with a [tool.<name>]
(box profile show). Box adds the rules mcp_notes_spawn and
mcp_notes_call for the server.
…the local profile

## Problem

Build makes the gateway routes of the AgentCore Runtime box profile from agentcore.json and the Box network model. It does not make them from the local box profile. Thus the Runtime profile does not have the keys of an `[egress.<name>]` entry or of an HTTP `[mcp.<name>]` server that the renderer does not know. The `gateway` rule of the derivation was a stub, and the derived profile had no gateway routes.

## Solution

The `gateway` rule (`runtimeProfile/rules/gateway.ts`) writes the gateway routes into the derived profile:

- Each host of an `[egress.<name>]` entry that has a gateway target gets `[egress.<target>]`. This route has one backend to `${{ inputs.gateway.url }}/<target>`, with a bare `aws://` signer for the build region. The rule removes the `secret`, because the gateway target sends the credential. The other keys of the entry stay.
- Each HTTP `[mcp.<name>]` server keeps its name and its other keys, and gets the same backend. The rule keeps only an `env://` secret, with no `inject`.
- Each passthrough target with no entry gets a route: `bedrock`, `agentcore`, a host that only a permit names, and each other passthrough target of the gateway. A target of an HTTP MCP server that only a pack has becomes that server.
- The rule finds the list of targets that build writes. It keeps each target without the `egress-` prefix, and each `egress-` target of a host. It removes the other `egress-` targets. It adds the target of each other host.
- The rule removes an entry if the policy denies all of its hosts. The renderer of agentcore.json also removes it, and the Box network model gives a warning for it.
- The rule removes an entry with no host in the Box network model. Box keeps each correct entry in its resolution, so the model has no host for an entry only when the model rejects that entry. The model then gives a problem with the key and its file:line:column, and build stops. A second problem from the rule gives the same entry two times.
- Two passthrough targets for one host cause the same `InputValidationError` that `runtimeGatewayRoutes` causes.
- The rule does not change a stdio `[mcp.<name>]`. The `refusals` and `paths` rules change it.

For these tables, the output of the rule is the same output that `runtimeGatewayRoutes`, `runtimeGatewayRouteSection`, `runtimeMcpServerSection`, `runtimeMcpServers`, and `runtimeGatewayBackend` make. This change does not remove these functions. It does not give the derived profile to the runtime profile writer.

## Tests

- `gateway.test.ts`, "give the same [egress] and HTTP [mcp] tables on the first build": one project goes through `buildBoxNetwork`, the credentials, gateway targets, and default targets writers, and `renderRuntimeBoxProfile`. The derived `[egress]` and HTTP `[mcp]` tables are equal to the tables of the renderer. The test "on the next build" does the same from the agentcore.json of the first build.
- "give no second problem for an entry that the Box network model rejects, and no route": the model rejects a wildcard `[egress]` entry and an `[mcp]` server with a path, with one problem for each. The rule adds no problem.
- The other tests of `gateway.test.ts` examine each item above. Each test has a local profile in TOML, and the TOML or the problem that must come out.
- A mutation script made 16 changes to the rule, one change at a time. For each change, one or more tests found it.
- `box profile show --format json --full` (box 0.1.11-linux-preview.6, macOS) accepted the profile of the renderer and the derived profile of the first test project. The two resolved `[egress]` and `[mcp]` tables were equal.
- `bun run typecheck`, `bun run lint:check`, and `bun run format:check` gave no error. `bun test`: 5363 pass, 7 skip, 0 fail. At 94385bb it gave 5348 pass, 7 skip, 0 fail, so the 15 new tests pass and no test of 94385bb stopped passing.

Not in the tests: a host with an API key and no credential, if the credentials writer cannot add one. The gateway targets writer does not write the target of that host, and the renderer gives the host no route. The rule gives the host a route to that target.
… local profile

The additions rule of deriveRuntimeProfile did not change a table. Thus
the Runtime profile from deriveRuntimeProfile had no box/agentcore pack,
no Runtime command, and no execution role on the CloudWatch targets.
This commit gives the rule its work. The rule moves no path, because the
paths rule comes after it. Build does not use this Runtime profile at
this time.

- packs: the packs of the user stay in their sequence. The rule adds
  box/agentcore, and box/agentcore-codezip for CodeZip, when the list
  does not have them.
- [profile] name: the name of the project.
- [options] bedrock.region: the build region, as a dotted key or as a
  key in quotes, or when the profile has box/bedrock. The other options
  stay.
- [agent] command: the command of the template becomes the Runtime
  command of the template. A command of the user stays, but without
  --reload and --reload-dir.
- [agent.env]: LOCAL_DEV goes. A value of the template becomes its
  Runtime value. A variable of the template that the user removed stays
  removed. A value of the user stays. The rule sets AWS_REGION (only
  without box/bedrock), AWS_DEFAULT_REGION, and the 2 AWS stand-ins,
  when the user does not set them. On CodeZip, PYTHONPATH starts with
  the ffi shim.
- [agent.filesystem]: each Runtime grant of the template comes first.
  A grant of the template that the user removed stays removed. Each
  grant of the user follows. An empty list goes.
- [[agent.ingress]]: the ingress of the template becomes its Runtime
  ingress. Each other ingress listens on 0.0.0.0, on the same port.
- [telemetry]: each CloudWatch target keeps its keys. It gets
  secret.ref = "aws://", and the deploy region when it has no region.
  The rule adds each CloudWatch target of the context that the local
  profile does not have. A target of a different type stays.
- policies, and each key that the rule does not change, stay.
- runtimeProfileHeader gives the comment lines of the Runtime profile.

Tests: rules/additions.test.ts. One test gives each template that
agentcore create writes to renderRuntimeBoxProfile and to
deriveRuntimeProfile: CodeZip with HTTP, MCP, A2A, and AGUI, and a
container with HTTP and MCP, with Bedrock or OpenAI, with and without
memory, and with and without CloudWatch telemetry and policies. For all
96 inputs, the packs, policies, profile, options, agent, and telemetry
tables are the same. Other tests show each change above, a key that
build does not know, and that the rule changes no table that it gets.
For each of 29 mutations of the rule, 1 or more tests show an error. box
0.1.11-linux-preview.6 on macOS (box profile show --full) accepts the
CodeZip and container profiles from deriveRuntimeProfile.
…efusals rule

addBoxGatewayTargets takes no project root on box-integration
(aws#2853). The stdio server of the gateway fixture now
starts a program in the code folder, because the refusals rule refuses
a system program on a CodeZip runtime. The gateway rule does not change
a stdio server, so the tests prove the same thing.
On AgentCore Runtime, a box with no cloudwatch_logs target sends its
records to no log group. Thus the records of the box are not in the log
group of the runtime, where the agent writes its logs. The runtime ID is
part of the name of that log group, and agentcore build cannot know the
ID, because deploy makes the runtime.

This commit makes the change of e2bdcd6 on dev in the Runtime profile
that deriveRuntimeProfile makes. When the derived profile has no
cloudwatch_logs target, the additions rule adds [telemetry.agentcore]
last. Its name is agentcore_default when a target has the name
agentcore. The target holds no literal value: box fills it when the run
starts.

- region is ${{ inputs.aws.region }}, from AWS_REGION.
- log_group and log_stream are ${{ inputs.runtime.log_group }} and
  ${{ inputs.runtime.log_stream }}. The box/agentcore pack has the 2
  inputs. They read the x-aws-log-group and x-aws-log-stream keys of
  OTEL_EXPORTER_OTLP_LOGS_HEADERS. The Runtime sets this variable to
  /aws/bedrock-agentcore/runtimes/<runtime ID>-DEFAULT and otel-rt-logs.
- include is deny, permit, and trace. secret.ref is "aws://".

A cloudwatch_logs target of the user, or one that box resolves from a
pack, replaces the default target. The rule keeps it with its keys, and
signs it as before. A cloudwatch_traces target or a target of a
different type does not replace the default target.
runtimeProfileHeader(context, profile) adds a comment line that names
the default target.

IAM: this commit adds no grant. The Runtime construct of aws-cdk-lib
2.269.0 gives the execution role logs:CreateLogStream and
logs:PutLogEvents on log-group:/aws/bedrock-agentcore/runtimes/*:
log-stream:*, in its account and region. The L3 at box-integration
(1.0.2) makes the role with that construct. The telemetry policy of the
CLI reads the CloudWatch targets that box resolves in the local profile,
not the Runtime profile. A target with an input in its log group or its
region is not in that list, so build writes no grant for the text of
the input, and build does not stop. box-integration grants
xray:PutTraceSegments for an X-Ray target before this commit, so this
commit does not include 9014fe3.

Box reads a key of a list variable only with
[strands-agents/staging-boxy#625](https://github.com/strands-agents/staging-boxy/pull/625).
Box 0.1.11-linux-preview.6 stops on the new pack with this error:
"holds `key`, which is not a declaration key". The pinned box must have
that change before a deploy of this commit.

Tests: rules/additions.test.ts. The test of the created templates now
has 144 inputs, with no telemetry, with CloudWatch logs and traces, and
with traces only. The tables are the same as the tables of
renderRuntimeBoxProfile, with the default target when no target is
cloudwatch_logs. Other tests show the full default target, that each
value of the target names an input of the pack, that a cloudwatch_logs
target of the user or of a pack replaces it, that a cloudwatch_traces
target or a third-party target does not replace it, the name
agentcore_default, and the header line. boxProfile.test.ts shows the 2
inputs of the pack. boxNetworkSource.test.ts shows that a
cloudwatch_logs target with inputs gives no telemetry grant, and no
failure or warning. For each of 10 mutations of the new code, 1 or more
tests show an error. The 29 mutations of the first commit continue to
show an error.

A synth of a scratch agent-python-strands-box-container project, with
the L3 at box-integration (c8019bc), holds the LogStreamAccess
statement on the role of the runtime. A box from
[fd15d288](https://github.com/strands-agents/staging-boxy/commit/fd15d2884993458379ce15071999eb52b2a597c0)
filled the default target of the CodeZip and container profiles with
box profile show. The values were the log group and the stream of the
variable, and the region of AWS_REGION. That box accepts only the @box/
pack names, so a copy of each profile and pack used them for that check.
There was no deploy.
[aws#2857](aws#2857)
changes the AgentCore Runtime profile that renderRuntimeBoxProfile
writes, and adds five box templates. The rules did not have these
changes, so the derived profile was different from the profile of the
old renderer:

- [d6eec45](aws@d6eec45)
  signs each Box gateway backend for ${{ inputs.aws.region }}, the
  region of the Runtime. The gateway rule signed it for the build
  region.
- [3df66a2](aws@3df66a2)
  and
  [f1f55b8](aws@f1f55b8)
  write [project] access, and a CodeZip local profile gets
  [tool.uname.filesystem] deny_write for the venv. The Runtime profile
  has no venv, so the old renderer wrote no [tool.uname]. The derived
  profile kept that table, with the venv path moved to the code
  directory.

With this change:

- The gateway rule signs each backend for ${{ inputs.aws.region }},
  which the agentcore pack reads from AWS_REGION. The build region
  does not go into a backend.
- The additions rule replaces each [tool.<name>] table that the local
  profile keeps as the template writes it with the Runtime table of the
  template. The Runtime template has no tool table, so [tool.uname]
  goes. A tool table that the user writes or changes stays.
- [project] goes through as the local profile has it. The old renderer
  wrote the same value for the local and the Runtime profile.

Tests: additions.test.ts "deriveRuntimeProfile on each box template of
create" compares the whole derived profile with renderRuntimeBoxProfile
of box-integration (f5503f0) for each of the seven box templates, the
model provider of the template and OpenAI where the template lets the
user change it, with and without Memory, and with three telemetry
inputs: 66 inputs. The test that compares the owned tables for each
build and protocol also compares [project] and [tool]. additions.test.ts
"removes the [tool.uname] table that a CodeZip template writes, and
keeps each tool table of the user". gateway.test.ts "gives each host of
an entry with several destinations its own route, signed for the
Runtime's region and not the build region", and the tests that compare
the gateway rule with renderRuntimeBoxProfile.
…local profile

Build staged the AgentCore Runtime profile that renderRuntimeBoxProfile
made from agentcore.json and from the Box network model. That renderer
did not read the local profile of the runtime. Thus each stdio
[mcp.<name>] server and each [tool.<name>] of the local profile was not
on AgentCore Runtime, and build gave no message.

With this change, the runtime profile writer stages the profile that
deriveRuntimeProfile makes from the local profile, with the comment
lines of runtimeProfileHeader. buildBoxNetwork keeps the profile and
its comment lines in BoxNetwork.runtimeProfile and
BoxNetwork.runtimeProfileHeader. A staged runtime with no Box network
stops build with a message, because the writer has no profile for it.

- renderBoxProfile writes only the local profile.
  runtimeAgentTemplate gives the [agent] table of a box template on
  AgentCore Runtime, in the paths of the local profile. The additions
  rule gives that table to each value that is the template's own, and
  the paths rule then moves its paths. Thus only the rules move a path
  to AgentCore Runtime.
- This commit removes renderRuntimeBoxProfile, runtimeGatewayRoutes,
  runtimeGatewayRouteSection, runtimeMcpServerSection,
  runtimeMcpServers, runtimeGatewayBackend, runtimeTelemetrySection,
  runtimeRegionEnv, RUNTIME_AWS_SIGNER, RUNTIME_AWS_STAND_IN_LINES, the
  Runtime branch of renderBoxProfile, and its runtimeRoutes and
  runtimePolicies parameters. The rules do this work.
- cloudWatchTelemetry keeps its CloudWatch filter. The telemetry policy
  writer reads it for the IAM grant. The refusals rule stops build for
  a target of a different type in the local profile.
- The guide tells how build derives the Runtime profile.

The derived profile is the same as the profile of the old renderer for
each box template, with the default telemetry target. Only the
sequence of the keys is different. Before this commit removed the
renderer, a test wrote the tables of the renderer of box-integration
(f5503f0, with
[aws#2857](aws#2857))
into runtimeProfile/__fixtures__/old-renderer-tables.json: the owned
tables for 72 inputs (CodeZip HTTP, MCP, A2A, and AGUI, container HTTP
and MCP, Bedrock and OpenAI, with and without Memory, and 3 telemetry
inputs), the whole profile for 66 inputs of the seven box templates of
create, and 4 gateway inputs.

Tests: additions.test.ts "gives the tables the old renderer wrote" (72
inputs), "gives the whole profile that the old renderer wrote" (66
inputs), and gateway.test.ts "the gateway rule and the Runtime renderer it
replaced" compare deriveRuntimeProfile with that file.
boxProfile.test.ts "runtimeAgentTemplate". boxNetworkWriters.test.ts
"writes the Runtime profile and a byte copy of each policy file beside
it" and "stops for a runtime that it stages with no derived Runtime
profile". The staging, build, and cdk tests stage the derived profile
of their model. The tests of the old renderer are removed: the rule
tests and the fixture cover them.
start.py exported sys.executable as BOX_PYTHON. When the Python of the
Runtime has the name python or python3, box refuses each stdio MCP
server that runs on ${{ inputs.python.path }}, because these names are
the interpreter aliases of box. The paths rule moves the venv's Python
of a stdio server to that input.

box_python in start.py gives the Python by its versioned name:
python3.<minor> beside it, else the file that it links to, else the
same path. start.py runs main() only as __main__, and it imports
tomllib only in main(). Thus a test can read box_python on Python 3.9.

Tests: boxStartPy.test.ts gives box_python a python3 with a versioned
file beside it, a python link, a versioned name, and a python3 with no
other name, with python3 from PATH. It also examines that start.py
exports the value of box_python. Not tested: start.py on AgentCore
Runtime.
[strands-agents/staging-boxy#570](https://github.com/strands-agents/staging-boxy/pull/570)
gives each pack and plugin that box ships the name @box/<name>. A box
with that change refuses the previous box/<name> name. The next box
release has it. Thus that box refuses each local profile that create
writes, and each Runtime profile that build stages.

With this change, the CLI writes these names:

- @box/base and @box/bedrock, in each local profile that create writes,
  and in each Runtime profile. BOX_BASE_PACK and BOX_BEDROCK_PACK are
  the names. The renderer, the bedrock.region copy of build, and the
  additions rule use them.
- @box/agentcore and @box/agentcore-codezip, in the packs of the Runtime
  profile and in the [pack] name of each pack that build writes. The
  path of each pack does not change.
- The comments of the code, of Dockerfile.template, of start.py, and of
  the guide use the new names.

Build does not change the profile of the user. When the local profile
names box/<name> in packs or in plugins, build stops before it starts
box. The message gives the file, each previous name, and its @box/
name.

This change comes from the local commit 967cc9f on the branch
dev/runtime-log-group-from-env, in the worktree
/Volumes/workplace/box-v3/agentcore-cli-devlog. The code of this branch
is different, so the change is made again here. The Runtime profile
fixture of the replaced renderer gets the new names. The open routes
fixture for a list of destinations is the output of box profile show
from a box with
[strands-agents/staging-boxy#625](https://github.com/strands-agents/staging-boxy/pull/625):
only its pack name changed. The fixture of 0.1.11-linux-preview.6 stays
the output of that box, with box/base.

Tests: boxNetworkSource.test.ts "stops before box runs when the profile
names a pack or a plugin that box ships by its old box/ name" and "runs
box for a profile with only @box/ names and names of its own". The
other tests examine the new names.
Box 0.1.11-linux-preview.6 refuses the profiles of this branch: it does
not know the @box/ pack names, and it refuses the key of an input, which
the default telemetry target reads. 0.1.11-linux-preview.7 has
[strands-agents/staging-boxy#570](https://github.com/strands-agents/staging-boxy/pull/570)
and
[strands-agents/staging-boxy#625](https://github.com/strands-agents/staging-boxy/pull/625).

bun scripts/bump-box-release.ts --box 0.1.11-linux-preview.7 wrote
boxRelease.json from the SHA256SUMS.txt of the release
(https://github.com/mquang-amazon/box-releases/releases/tag/v0.1.11-linux-preview.7).
The Linux SHA-256 is
782290ca3f0f0de3faa6c3943a0b51d521f16b135178ab7e4425986a97ee7622. The
ffi shim stays at 0.1.11-linux-preview.2. The README and the tests that
name the pinned box name preview.7. @box/base of preview.7 has one tool,
uname, so BOX_BASE_PROJECT_WRITE_TOOLS does not change, and its comment
names preview.7.

Tests: boxProfileResolver.test.ts names preview.7 in the install
message. The other tests read the pin from boxRelease.json.
…host

The Runtime profile has one route to the Box gateway for each host, and
the gateway has one target for each host. A local profile can give one
host two routes: two [egress] entries that name it, or one entry that
names it two times. No test said what build then does, so a change could
drop the keys of one entry, or route a host twice, and give no message.

The tests pin these rules, end to end from box profile show to the
derived Runtime profile:

- Two [egress] entries that name one host stop build with one
  EGRESS_DESTINATION_OVERLAP problem, at the second entry, that names
  the two entries. This applies to two open routes, and for a route with
  a secret and an open route. Box itself refuses two routes with a
  secret to one host.
- One entry that names its host two times, as api.example.com and
  api.example.com:443, gets one target and one route.
- The additions rule adds @box/agentcore and @box/agentcore-codezip only
  when the profile does not list them.
- The additions rule adds the ffi shim to PYTHONPATH only when
  PYTHONPATH does not start with it.

Tests: boxNetworkSource.test.ts "stop build for %s to one host, with one
problem that names both entries" (two inputs) and "gives an entry that
names its host twice one target and one route". additions.test.ts
"adds no Runtime pack that the profile already lists, on CodeZip and on
a container" and "adds no second ffi entry to a PYTHONPATH that starts
with the ffi shim". With box 0.1.11-linux-preview.7 on macOS, box
profile show accepts two open routes, and a route with a secret and an
open route, to one host, and refuses two routes with a secret.
…ip runtime

On a CodeZip AgentCore Runtime, the paths rule moves each path of the
code folder to ${{ inputs.code.dir }}, and the agent gets exec on that
folder. box refuses a write grant in a folder that the box can run
files from. Thus a local write grant in the code folder, for example
[mcp.notes.filesystem] write = ["${{ workspace }}/app/agent/notes"],
gave a Runtime profile that box refused when the agent started on the
Runtime. Build ran box profile show only on the local profile, where
the agent has no exec on the code folder, so build gave no message.

The real check found this. With box 0.1.11-linux-preview.7, box profile
show of the derived profile of such a server stopped on macOS and in
the Linux image: "the `exec` folder .../app/agent holds the write grant
.../app/agent/notes, so the workload can run a file it writes".

With this change, the refusals rule stops build for each write or
write_file grant of [agent], a stdio [mcp.<name>], or a [tool.<name>]
that is in the code folder on a CodeZip runtime
(RUNTIME_WRITE_IN_CODE). The message names the key, the path, and the
reason. A container runtime keeps its grants, because the image runs
the same paths under agentcore dev and on the Runtime.

Tests: refusals.test.ts "stops for a write grant in the code folder of
[agent], a stdio [mcp], and a [tool], on a CodeZip Runtime only
(RUNTIME_WRITE_IN_CODE)". The paths rule test of the stdio server no
longer has a write grant in the code folder.
…mports it

boxStartPy.test.ts imports start.py from src/assets/templates/box-codezip
with python3 -I. A Python that writes bytecode then leaves a
__pycache__ folder in that template folder, and build copies src/assets
into the package. With a Python 3.12 import, the folder came to exist.
The test now runs python3 with -B, which writes no bytecode.

Tests: boxStartPy.test.ts passes, and git status shows no new file
after it.
…entry

The derived Runtime profile keeps each pack of the local profile. The
gateway rule named each [egress] route after its gateway target, for
example [egress.egress-anthropic] for the [egress.anthropic] entry of
@box/anthropic. On AgentCore Runtime, the pack adds its own
[egress.anthropic] again, so the profile had two routes to
api.anthropic.com, and box refuses that when the agent starts. The same
happened when the profile changes an entry of a pack, for example
[egress.anthropic] secret.ref = "env://MY_KEY". The renderer that the
derivation replaced removed each pack of the user, so it did not have
this problem. The independent review of this PR found it.

With this change, the route of an entry with one host has the name of
the entry. Its backend still names the gateway target. box merges the
table of the pack with the route of the same name, as it merges
[egress.bedrock] of @box/bedrock with the bedrock route of each box
template. A route keeps the name of its target when its entry has more
than one host, when it serves no entry, or when a target of the entry's
name serves another host.

The route names on the Runtime are different from the names of the old
renderer, for example [egress.github] and not [egress.egress-github].
The routes are the same. The tests that compare the gateway rule with
the recorded output of the old renderer compare the routes under the
new names.

Tests: gateway.test.ts "gives the route of an entry %s the name of the
entry, so the table of the pack merges with it" (an entry that a pack
adds, and an entry that the profile changes) and "names a route after
its target when a target of the entry's name serves another host".
manager.boxNetwork.test.ts and boxNetworkSource.test.ts expect the
entry names.

box 0.1.11-linux-preview.7 on macOS (box profile show), with packs =
["@box/base", "@box/anthropic"] and a gateway route to
api.anthropic.com: under the name egress-anthropic, box refuses the
profile ("`egress-anthropic` and `anthropic` both name host
"api.anthropic.com""). Under the name anthropic, box accepts it, and
merges the secret of the pack with the backend of the route. Not
tested: a call through that route on AgentCore Runtime.
… CodeZip Runtime does not have

The refusals rule examined only a path that names ${{ workspace }} or
${{ home }}, and the program of a stdio server or a tool. Thus build
let these through to a CodeZip Runtime, where box refuses them when
the agent starts:

- a grant or a value in the home folder that names no ${{ home }}: ~,
  ~/data, /Users/me/data, or /home/me/data. box expands ~ to the home
  folder, which is empty on the Runtime, and the Runtime has no /Users
  or /home of the host;
- an [agent] command of the user that starts a program that is not the
  venv's Python or a file in the code folder, for example
  /opt/homebrew/bin/python3. The comment of the rule said that the
  additions rule writes the [agent] command, but that rule keeps a
  command of the user.

The independent review of this PR found these.

With this change, the refusals rule gives RUNTIME_PATH_NOT_FOUND for a
value that starts with ~, ~/, /Users/, or /home/, and
RUNTIME_PROGRAM_NOT_FOUND for the [agent] program, as it does for a
leaf. The command of the template moves to the Runtime's Python, so it
is not a problem. A container runtime keeps each path and program. Two
comments that were not correct now say what the rules do.

Other absolute paths stay as the local profile has them, for example
/etc/ssl/certs: build cannot see the file system of the Runtime.

Tests: refusals.test.ts "stops for an [agent] program of the user that
build cannot find, on a CodeZip Runtime only" and "stops for the host
home path %s, on a CodeZip Runtime only (RUNTIME_PATH_NOT_FOUND)" (4
paths). The test fixtures that used [agent] command = ["/bin/echo"] on
CodeZip now start a program in the code folder.
…emoved

The additions rule gives each [agent.filesystem] list the Runtime
grants of the template, and leaves out a template grant that the user
removed. It compared the grants by value. The local grants of the
template are tables with optional = true, and its Runtime grants are
strings, so no Runtime grant was equal to a local one. Thus each
CodeZip agent got exec on the code folder and on the Runtime Python,
and read on /usr/lib64 and /lib64, whatever its local profile had. An
[agent] with no filesystem table got exec on the whole code folder,
which holds .box-dist/box. The independent review of this PR found
this.

With this change, a grant is the same as another when its path is. A
list gets each Runtime grant of the template only when the local list
keeps each grant of the template. When the user removed a grant of the
template, the list gets only the Runtime grants that it names. Thus the
Runtime gets no grant that the local profile does not give. The profile
that create writes gets the same grants as before.

Tests: additions.test.ts "gives a list no Runtime grant of the template
when the user removed a grant of the template from it" and "gives an
[agent] with no filesystem table no grant". The 72 and 66 inputs of the
created templates give the same profile as before.
…ch target of a pack

A [telemetry.<name>] table with no kind adds keys to the target of that
name that a pack gives. The refusals rule stopped build for it ("kind
is not set"), and the additions rule did not sign it with the execution
role. The independent review of this PR found this.

With this change, when box resolves a CloudWatch target of that name,
the refusals rule takes the table, and the additions rule signs it with
a bare aws://, in the region of the resolved target. A cloudwatch_logs
target of this kind replaces the default log target. A table with no
kind and no CloudWatch target of its name still stops build.

Tests: refusals.test.ts "takes a [telemetry] table with no kind that
adds to a CloudWatch target of a pack". additions.test.ts "signs a
table with no kind that adds to the CloudWatch target of a pack".
…of the derivation

The guide said that build writes the Runtime profile in
.box/<runtime>/aws/ and copies it into .box-dist/.
[aws#2859](aws#2859)
changed this: build stages the profile, its policy files, and box in
.box-dist/, and writes a copy of the profile, the generated packs, and
the policy files into .box/<runtime>/aws/ for people to read. The list
of the stops of the derivation did not have the stops that this PR
adds.

The guide now says where build stages the profile, lists each stop
(the home paths, the program of the agent, and a write grant in the
code folder), and says that the route of an entry with one host keeps
the name of the entry.

Tests: none; this changes only the guide.
@SaiAbhishek98
SaiAbhishek98 requested a review from a team November 20, 2026 03:46
@codecov-commenter

codecov-commenter commented Nov 20, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.46278% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.79%. Comparing base (b805512) to head (d6330f6).

Files with missing lines Patch % Lines
src/core/project/runtimeProfile/rules/additions.ts 99.15% 3 Missing ⚠️
src/core/project/runtimeProfile/rules/gateway.ts 98.61% 2 Missing ⚠️
src/core/project/runtimeProfile/rules/paths.ts 97.53% 2 Missing ⚠️
Additional details and impacted files
@@                 Coverage Diff                 @@
##           box-integration    #2866      +/-   ##
===================================================
+ Coverage            96.75%   96.79%   +0.04%     
===================================================
  Files                  757      766       +9     
  Lines                65659    66654     +995     
===================================================
+ Hits                 63528    64519     +991     
- Misses                2131     2135       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review of 0a00f77f..d6330f6d. These are new commits plus one merge (9fb98f98), not a rebase. Approving. The blocking CI failure is fixed and every earlier non-blocking item is addressed. CI at d6330f6d: verify / Linux, verify / Windows, verify / macOS, CodeQL and Analyze all pass.

Earlier items, now addressed

  • BLOCKING (CI), fixed. 71864dd2 replaces the chmod trick with a ReadWriteJson that refuses only the write of agentcore.json. The test now asserts that exact error and that no warning came before it, so it works as root, on Windows, and also proves the ordering.
  • Orphaned JSDoc on assertNotBoxProject: fixed in 5172252f.
  • "workload_port is undefined" warning: fixed in cc139a75, with a test.
  • routeKey taking a first host that has no target: fixed in ed0e4b03. The new test uses @box/anthropic with an earlier denied host, which pins the pack-collision case.
  • [mcp] side of withoutUnsentRoutes, and the note on BoxNetwork.runtimeProfile: fixed in f9227970.
  • Optional startFolder defaulting to the old layout, and "build accepts both layouts" overstating it: both go away in eb8685bd. runtimePaths(runtime) now always maps the CodeZip code folder to ${{ workspace }}, which matches boxStartFolder from codeLocation (#2865). I found no remaining text that claims old-layout support.

The merge of box-integration b8055125 (#2865)

  • publishInstall and its 3 tests are kept. Only the ffi call site is gone, which is expected because this PR removes the shim.
  • boxStartFolder(runtime) from build/codeLocation is identical to box-integration. dev/box.ts and boxNetworkSource.ts both call it.
  • Both files are kept: backends/boxStartPy.test.ts from #2865 (now written with serializeRuntimeProfile) and this PR's templates/boxStartPy.test.ts.
  • The other #2865 changes, the envLocal upsert fixes and the e2e suite, are unchanged from base.
  • The must-survive markers from #2845 through #2862 are still present: ENV_LOCAL_RELATIVE_PATH, writesBedrockRoute, the Secrets Manager checks, regionFromConfigFile(this.processEnv), the Dockerfile's curl --retry 3 and tar --no-same-owner, the xray grants and <runtime>-box-egress. Counts match base.

Plan mapping

9637a938, 6ce73631 and 853a8a56 bring MQ-8 (#2867) scope into SA-5. They match dev: 264da50a and 44779170 (no ffi shim), 7de308e8 (pin preview.9), and dev's BOX_MINIMUM_VERSION and old-box hint. Dev's boxRelease.json is byte-identical. Some changes exist only on box-integration: BOX_OTHER_MACHINE_HINT and BOX_MINIMUM_RELEASE_PAGE (dev's BOX_INSTALL_HINT has no macOS fallback), the review fixes, and eb8685bd. Like renderRuntimeBoxProfile, these need a back-merge into dev before SA-6 or DOCS-2.

New findings (all non-blocking)

  1. Stale doc (comment accuracy). e2eTest/README.md L49-51, from #2865, still says the py_strands_box_3_10..3_13 cases "pass only once box runs CodeZip agents without the ffi shim (#2867): until then boxRelease.json pins a shim for PYTHON_3_14 only". This PR removes the shim and the ffi block, so the paragraph is now wrong. Drop it or reword it. Dev has no such paragraph.
  2. refuseOldShippedNames. I agree it is this PR's own stop and not the one #2867 dropped. But eb8685bd removed the old-layout path case because "Box is only for new projects", and a box/<name> pack name can only come from a profile written before @box/. By the same rule this stop is compatibility code for old projects. Your call. If it stays, it still merges silently into #2867 (see below).
  3. gte(BOX_RELEASE.version, BOX_MINIMUM_VERSION) in boxRelease.test.ts. This passes only because the prerelease identifier mquang sorts after linux in ASCII. A newer pin with a different tag, say 0.1.11-amzn.preview.1, would fail the test even though it is a later box. A comment, or a list of allowed tags, would avoid a confusing failure on the next bump. Nit.
  4. Shim-free CodeZip on the Runtime has no automated coverage. Your note says this too: the real check resolves profiles but does not run the agent on a microVM, and the Box deploy e2e is opt-in. This is the same risk #2867 carries, so it is not blocking here. Please run the opt-in box deploy e2e once before SA-6.

Coordination with #2867 (non-blocking)

#2867 is now at c6cd3f4b, which is f40ebce7 plus a merge of box-integration b8055125.

  • A trial merge of it into d6330f6d gives 10 text conflicts: README.md, the Dockerfile.template comment, boxCodeZip.test.ts, boxRelease.ts, boxRelease.test.ts, boxNetworkWriters.test.ts, boxProfileResolver.ts, boxProfileResolver.test.ts, templates/boxProfile.ts and templates/boxProfile.test.ts.
  • The silent ffi PYTHONPATH merge is gone, because this PR removes the prefix.
  • Only refuseOldShippedNames, with its call and test in boxNetworkSource.ts, still merges silently.
  • This PR now carries #2867's shim removal and pin. What #2867 adds on top is the exact-pin boxReleaseFor with no SHA256SUMS.txt fallback; this PR keeps the base fallback.
  • If this PR merges first, #2867 could shrink to that change. Your list in the boxNetworkSource.ts thread covers the hand steps for the other order.

Known flaky CI on the base

The Windows transactionSearch EFAULT test and the 5 s macOS screen-test timeouts are known flakes on the base. Neither failed on this run.

@SaiAbhishek98
SaiAbhishek98 merged commit fa21200 into aws:box-integration Nov 20, 2026
7 checks passed
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…py only the targets box takes

The additions rule copied each cloudwatch_logs and cloudwatch_traces
table of the local profile to the Runtime profile. cloudWatchTelemetry
leaves out a target that box refuses when a run starts, for example a
log_stream with ":" or an empty include, so the telemetry policy gave
it no grant. Such a target also counted as a cloudwatch_logs target,
so the default [telemetry.agentcore] did not come in. Build passed, and
the run stopped when it started. The renderer that the derivation
replaced copied only the targets that box takes. Leo found this in the
review of
[#2866](#2866).

With this change:

- The refusals rule stops build for a CloudWatch table of the local
  profile that is not in context.telemetry, the targets that box takes
  (RUNTIME_TELEMETRY_REFUSED). The message names the table and the
  values that box takes. Build stops and does not remove the table,
  because box refuses the same table under agentcore dev: the local
  profile cannot run, and a Runtime profile with no such target would
  hide that.
- The additions rule copies only the CloudWatch tables that box takes.
  A table that box refuses does not reach the Runtime, and does not
  stop the default target.

Tests: refusals.test.ts "stops for a CloudWatch target that box refuses
when a run starts (RUNTIME_TELEMETRY_REFUSED)". additions.test.ts
"copies no CloudWatch target that box refuses, as it grants it nothing,
and adds the default target", the test of the old renderer that the
wiring commit removed. The refusals tests now give the rule the targets
that box takes from each profile, as build does.

(cherry picked from commit 4d165cd)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
From the review of Leo on
[#2866](#2866):

- The table of the gateway rule said that each [egress.<name>] becomes
  [egress.<target>]. Since 737e107, an entry with one host keeps its
  name. The table now gives the two cases.
- inProfileOrder removes problems by code, key, and reason, not by
  place. Its comment now says "each identical problem once".
- The comment of applyBoxNetwork said that staging renders the routes
  from the targets of the Box gateway. Staging writes the profile that
  each model derives, BoxNetwork.runtimeProfile.
- The message of the runtime profile writer said only "found no Box
  network". It also comes when a network has no derived profile, so it
  now says that too.

Tests: boxNetworkWriters.test.ts passes; no test reads the changed
part of the message.

(cherry picked from commit afe56a6)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
The gateway rule and the additions rule each had their own isTable,
and only the one of the additions rule left out a date. The two rules
also each had RUNTIME_AWS_SIGNER. Leo found this in the review of
[#2866](#2866).

The three rules now use isTable of projectPaths.ts, which takes only a
plain table, so a TomlDate is not a table. RUNTIME_AWS_SIGNER is in
types.ts, beside RUNTIME_INPUTS. The behaviour does not change.

Tests: the runtimeProfile and boxNetwork tests pass (414).
(cherry picked from commit 797ed4b)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
boxStartPy.test.ts makes symbolic links, sets file modes, and writes
#!/bin/sh files, and then runs python3. On Windows the tests skip only
because python3 is not on PATH there. A runner with python3 can fail
with EPERM on symlinkSync. Leo found this in the review of
[#2866](#2866).

Each test that uses these files now skips when python3 is not on PATH
or the platform is win32.

Tests: boxStartPy.test.ts passes on macOS (5).
(cherry picked from commit 5d2eb4a)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…he runtime turn it off

When the derived Runtime profile has no cloudwatch_logs target, build
adds [telemetry.agentcore]: box sends its deny, permit, and trace
records to the log group of the runtime. No command said so, no
document said what it costs or how long the records stay, and the
user could not turn it off without a cloudwatch_logs target of their
own. The pre-review of
[#2866](#2866)
found this, and Leo asked the guide to say that the target needs
OTEL_EXPORTER_OTLP_LOGS_HEADERS.

With this change:

- agentcore create and agentcore add runtime give a notice for each box
  runtime: what box sends, the log group
  /aws/bedrock-agentcore/runtimes/<runtime ID>-DEFAULT and the stream
  otel-rt-logs, that the log group is the Runtime's and stays after
  the runtime is removed, that CloudWatch Logs charges for the records,
  and how to send none. add runtime gives it after agentcore.json is
  written, so a failed write gives no notice.
- The Runtime profile gets no default target when the envVars of the
  runtime set DISABLE_ADOT_OBSERVABILITY to "true". This is the switch
  that the CLI already documents to turn off observability. The switch
  is not instrumentation.enableOtel: each box template writes
  enableOtel = false (#2862), because the agent in a
  box does not run under opentelemetry-instrument, and that says
  nothing about the records of box.
- The guide says what the target sends, that box does not start when
  the Runtime does not set OTEL_EXPORTER_OTLP_LOGS_HEADERS, the
  retention and the cost, and the two ways to change it.

Tests: additions.test.ts "adds the default target only when the envVars
do not set DISABLE_ADOT_OBSERVABILITY to true" (3 values).
manager.test.ts "writes the box profile into the agent's
.box/<name>/local folder" checks the notice of create.
manager.box.test.ts "add runtime gives the new runtime a box, its Box
gateway, and its own box profile" checks that the notice comes after
the write of agentcore.json, and "a failed write of agentcore.json
gives no notice of the default log target".

Dev port: dev does not add a box runtime with agentcore add runtime,
and it finds a box runtime by its start.py entry point or its
Dockerfile (runsAgentInBox), not by box.version. Thus the notice uses
runsAgentInBox in a Box project, and the add runtime tests of
box-integration that check the notice are not in this port. The create
test of manager.test.ts checks the notice.

(cherry picked from commit 981588a)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…oved a template grant

2913cd2 gave a list only the Runtime grants that the local list names
when the user removed one grant of the template from it. Then a CodeZip
agent lost read on /usr/lib64 and /lib64 and exec on the code folder,
where the Runtime installs the dependencies and their native modules,
so the agent could not start on the Runtime. The pre-review and Varun
in the review of
[#2866](#2866)
found this.

With this change, a Runtime grant of the template whose path the local
template list has stays only when the local list keeps it. A Runtime
grant that only the Runtime has always stays. Grants are still the
same when their paths are, so a grant of the user that is not optional
matches an optional grant of the template. An [agent] with no
filesystem table gets only the grants that only the Runtime has.

Tests: additions.test.ts "keeps the grants that only the Runtime has,
and no grant of the template that the user removed" (the read grant of
the uv Pythons removed) and "gives an [agent] with no filesystem table
only the grants that only the Runtime has".

(cherry picked from commit 086bc46)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…ROFILE to it

A local profile can set AWS_REGION or AWS_DEFAULT_REGION in
[agent.env], for example to call Bedrock in another region under
agentcore dev. The additions rule kept that value on the Runtime, so
the AWS SDKs in the box called a region whose hosts the Runtime profile
does not route. It also kept AWS_PROFILE, and AgentCore Runtime has no
AWS profiles. The pre-review of
[#2866](#2866)
found this.

With this change, the region of the Runtime replaces a region of the
user: ${{ inputs.aws.region }}, or, with @box/bedrock, the AWS_REGION
of that pack. AWS_PROFILE does not go to the Runtime. Build gives a
warning for each value that it does not use, with the key and the
profile.

Tests: additions.test.ts "gives the agent the region of the Runtime
over a region of the user, and says so" (with and without @box/bedrock)
and "sends no AWS_PROFILE to the Runtime, and says so".

(cherry picked from commit bbc6430)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…and warn for the rest

The refusals rule stopped build for some keys that the Runtime can do
without, and the home check read any string as a path. The pre-review
and Varun in the review of
[#2866](#2866)
found these.

With this change, on a CodeZip runtime:

- A deny or deny_write entry, or an optional grant, whose path is not on
  the Runtime does not stop build. The paths rule leaves it out of the
  Runtime profile, with a warning. A required grant with no place on the
  Runtime still stops build (RUNTIME_PATH_NOT_FOUND).
- A program at an absolute path of the system, for example
  /usr/bin/grep or /opt/homebrew/bin/python3, goes to the Runtime with a
  warning that build cannot check the Runtime image; box stops the run
  when the program is not there. This is one rule for the [agent], a
  stdio server, and a tool. A program in the project outside the code
  folder, in the home folder, or in the venv still stops build
  (RUNTIME_PATH_NOT_FOUND), and so does a program that PATH finds, such
  as npx (RUNTIME_PROGRAM_NOT_FOUND).
- The check for a host home path (~, ~/, /Users/, /home/) reads only a
  value that is a path: a filesystem grant, a word of a command, or a
  program. It reads each part of a : list and the value of a --flag=,
  as the ${{ home }} check does. An env value such as "/home/page" is
  not a path for this check.

On each runtime, a telemetry target of kind "file" does not stop build.
The additions rule leaves it out of the Runtime profile, with a warning,
because nothing reads the files of the microVM. Each other kind that is
not CloudWatch still stops build.

keyLabel moved from derive.ts to projectPaths.ts, so the refusals rule
does not import derive.ts, which imports the rules.

Tests: refusals.test.ts "stops for a program of %s that PATH finds, on
a CodeZip Runtime only (RUNTIME_PROGRAM_NOT_FOUND)" (3 tables), "carries
a system program of %s, with a warning that build cannot check it, on a
CodeZip Runtime only" (2), "reads each part of a : list and the value
of a --flag= in a command for a host home path", the optional grant in
"stops for each path that cannot move", and the file target in "stops
for each [telemetry] target that is not CloudWatch". paths.test.ts
"leaves out a deny entry and an optional grant that are not on the
Runtime, with a warning". additions.test.ts "leaves a target of another
kind as it is, and leaves out a file target with a warning".

(cherry picked from commit aa1e11c)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
… folder on the Runtime

On a CodeZip runtime, the paths rule moves the venv to the code folder.
So a local deny = ["${{ workspace }}/app/agent/.venv"] became
deny = ["${{ inputs.code.dir }}"] on the Runtime, and the agent could
not read its own code. Build gave no message. Quang found this in the
review of
[#2866](#2866).

With this change, the paths rule leaves out each deny entry on the venv
or in it before it moves the paths, with a warning that names the key
and the path. This is the same as for each other protective entry with
no place on the Runtime: build leaves it out and warns, and does not
stop. A deny_write entry on the venv stays, and moves to the code
folder, where it takes away only write access. The rule reads the venv
from the paths of the runtime, so it also holds when the local profile
names the code folder as ${{ workspace }}.

Tests: paths.test.ts "leaves out a deny entry on the venv or in it,
with a warning, and keeps deny_write on the venv".

(cherry picked from commit 797024a)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
The README said that two templates run their agent in a box, and that a
Box project holds one runtime, so add runtime and export harness refuse
it. Since #2857 there are seven box templates, and
since #2859 add runtime adds a box runtime to a Box
project. The pre-review of
[#2866](#2866)
found this. The paragraph now names the seven templates, says that each
runtime has its own box profile, says what add runtime and export
harness do in a Box project, and says that build derives the Runtime
profile from the local profile.

Tests: none; this changes only the README.

Dev port: the README of dev names the seven templates and the box
release already, and dev does not have the add runtime of
#2859. This port adds only the sentences on the local
profile of each box runtime and on the derived Runtime profile.

(cherry picked from commit cbd378c)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…ation

From the pre-review and the review of Leo on
[#2866](#2866).
No behaviour of build changes, except that an [mcp] server that names
a url or destinations and has no command is now an HTTP server for
the path rules too, as it was for the gateway rule.

- RuntimeProfileContext has no policyFiles: no rule read it. The
  policies key stays as the local profile has it.
- runtimeTools has no branch for a Runtime tool table of the template:
  the Runtime template has none.
- One isHttpServer, in projectPaths.ts, for the gateway rule and the
  path rules. One RUNTIME_LOGS_HEADERS_ENV, in templates/boxProfile.ts.
- These are no longer exports, as only their own module uses them:
  RUNTIME_PROFILE_RULES, RUNTIME_AWS_STAND_INS, runtimeRegionEnv,
  OBSERVABILITY_OFF_ENV, ProcessTable, BOX_BASE_PACK, and
  boxLocalProfileName.
- Three comments now say what the code does: the program check of the
  refusals rule, the summary of the gateway rule, and where the
  [egress] and [mcp] tables of the Runtime profile go.
- Two tests that only compared a constant list are gone: the sequence
  of the rules, and the list of the box templates.
- The comment of the box profile show fixtures says why the fixture of
  preview.6 names box/base.

Tests: the runtimeProfile tests pass (256); typecheck and lint pass.
(cherry picked from commit a4f44a1)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
… and of each leaf

On a CodeZip Runtime, the dependencies are in the code folder, and not
in a venv. When the local profile set its own PYTHONPATH, for example
"${{ workspace }}/app/agent/lib", the derived PYTHONPATH had the ffi
shim and that entry, but not the code folder, so `import strands`
failed when the agent started. Quang found this in the review of
[#2866](#2866).

With this change, the paths rule, after it moves the paths, gives the
PYTHONPATH of [agent], and of each stdio server or tool that runs the
Runtime Python, each entry one time, in its order, and adds
${{ inputs.code.dir }} at the end when the PYTHONPATH does not name it.
For a leaf, the ffi shim comes first; the additions rule puts it first
for [agent]. Two local entries that move to one Runtime path, as the
code folder and its venv do, become one entry.

#2867 removes the ffi shim from these lines. The PR
that merges second keeps the code folder.

Tests: paths.test.ts "keeps the code folder in the PYTHONPATH of
[agent] and of a leaf on the Runtime Python, one time".

(cherry picked from commit fa622c8)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…policies on one line

Varun asked in the review of
[#2866](#2866)
to keep staged_policies of #2862 with box_python, and
to make sure that the derived Runtime profile writes `policies` on one
line. On Python 3.10 there is no tomllib, and staged_policies reads that
line as a JSON list.

- boxStartPy.test.ts runs main() of start.py with its folders in a
  temporary folder and os.execve replaced. It checks the box that
  main() runs and its arguments, that BOX_PYTHON is what box_python
  gives, and that the profile and each policy file are copied. It runs
  one time with tomllib and one time with tomllib set to None, as on
  Python 3.10. This test replaces the test that read the text of
  start.py.
- derive.test.ts checks that serializeRuntimeProfile writes 30 policy
  files on one line, and that the line reads as a JSON list.

Tests: the two tests pass with python3 3.9.6 on the PATH. A manual run
of main() gave the same copies with Python 3.10.21 (no tomllib), 3.12.14
(tomllib), and 3.9.6 (no tomllib).

(cherry picked from commit 77d250e)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
… the local port

The additions rule kept the port of an [[agent.ingress]] that the user
changed, for example listen = "127.0.0.1:8090", and only moved it to
0.0.0.0. AgentCore Runtime sends the requests of a protocol only to the
port of that protocol (8080 for HTTP), so the agent got no request.
Quang found this in the review of
[#2866](#2866).
This reverses the earlier choice to keep a port that the user changed.

With this change, the first ingress of the Runtime profile listens on
0.0.0.0:<port of the protocol> (boxIngressPort), for CodeZip and for a
container. It forwards to the workload port of the template when the
agent keeps the command and the port variable of the template, because
the Runtime form of the template starts the agent on the same port as
the local form. Else it forwards to its own workload_port, where the
agent of the user listens under agentcore dev too. Build gives a
warning for each port that changes. Each other ingress listens on
0.0.0.0 on its own port, as before.

Tests: additions.test.ts "listens on the port of the protocol on the
Runtime when the user changed the local port, and says so" and
"forwards to the workload port of the template while the agent keeps
its command, and else to the port of the user". The created templates
give the same ingress as before.

(cherry picked from commit 664e074)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
737e107 named the route of an entry after the entry only when the
entry had one host. With packs = ["@box/anthropic"] and a local
[egress.anthropic] for api.anthropic.com and statsig.anthropic.com,
each route had the name of its target, so the [egress.anthropic] of the
pack for api.anthropic.com stayed beside the route to that host, and
box refused the two routes. Quang found this in the review of
[#2866](#2866).

With this change, the route of the first host of an entry has the name
of the entry, and each other host of the entry has a route with the
name of its target. box merges the table of the pack with the route of
the same name, and takes the destinations of the profile.

box 0.1.11-linux-preview.7 on macOS (box profile show), with packs =
["@box/base", "@box/anthropic"]: with two routes named after their
targets, box refuses the profile ("`egress-anthropic-api-anthropic-com`
and `anthropic` both name host "api.anthropic.com""). With the route of
the first host or of the second host named anthropic, box accepts it.

Tests: gateway.test.ts "names the route of the first host of an entry
of a pack after the entry, and each other after its target". The test of
an entry with several hosts, and the comparisons with the old renderer,
expect [egress.models] for the first host.

(cherry picked from commit 0744958)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…ation

The guide did not have the changes of this batch to the derivation,
and it did not say that box refuses, under agentcore dev, a stdio
server or a tool that the venv Python runs. The pre-review of
[#2866](#2866)
asked for this.

The guide now says how the routes get their names, what the agent env
and the ingress get on the Runtime, which values stop build and which
give a warning, and that a CodeZip local profile needs
[project] access = "read" to run a stdio server or a tool on the venv
Python: box 0.1.11-linux-preview.7 refuses it with "write", which the
templates write.

Tests: none; this changes only the guide.
(cherry picked from commit 0a00f77)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…o workload_port

When the first `[[agent.ingress]]` of the local profile had no
`workload_port` and the agent kept the command of the template, the
additions rule said "workload_port is undefined". The user wrote nothing
that changes, so the rule gives no warning for it. The review of Leo on
[#2866](#2866)
found this.

Tests: additions.test.ts "gives no workload_port warning when the local
first ingress sets none and the agent keeps the template command".

(cherry picked from commit cc139a7)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…ntry that has a target

routeKey took the first host of the entry, also when that host had no
target, for example a host that the policy denies. Then each route of
the entry got the name of its target, and the collision with an entry of
a pack, such as `[egress.anthropic]` of `@box/anthropic`, came back. The
rule takes the first host of the entry that has a target. The review
of Leo on
[#2866](#2866)
found this.

Tests: gateway.test.ts "names the route of the first host of an entry
that has a target after the entry, when an earlier host has none". The
test fails when the rule takes a host with no target.

(cherry picked from commit ed0e4b0)
SaiAbhishek98 pushed a commit to SaiAbhishek98/agentcore-cli that referenced this pull request Nov 20, 2026
`box-integration` has three new changes: PR 5
([aws#2866](aws#2866)),
the pin of box 0.1.11-mquang.preview.9
([aws#2867](aws#2867)),
and `--containment`
([aws#2854](aws#2854)).
Two files had a merge conflict.

In `create` in `manager.tsx`, `box-integration` gives
`defaultLogTargetNotices`, and this branch gives `boxGatewayLogsWarnings`.
The merge keeps the two.

In the imports of `manager.boxNetwork.test.ts`, `box-integration` removes
`renderRuntimeBoxProfile`, and this branch adds `boxGatewayLogsNotice`.
The merge keeps only `boxGatewayLogsNotice`.

A test of `box-integration` makes sure that `add runtime` gives no
`warning` before the write of agentcore.json. The name of the test is "a
failed write of agentcore.json gives no notice of the default log
target". `addBoxRuntime` gave the logs `warning` before that write, thus
that test showed an error after the merge. The merge moves the logs
`warning` of `add runtime` to after the write, with the
`defaultLogTargetNotices` of `box-integration`. `create` also gives each
`warning` after the write.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants