[mquang-amazon]

Description

agentcore deploy runs a Python CodeZip agent in a box on AgentCore Runtime. Before this, only agentcore dev ran it in a box (#2790). Nothing shipped box to the Runtime or started it there. The Strands container template follows in a stacked PR.

• Start scripts: create writes start.py and start.sh into every Python CodeZip template (Strands HTTP/A2A/AG-UI, LangChain, minimal, FastMCP) and sets entrypoint to start.py. The Runtime needs a .py entry point, so start.py hands over to start.sh. start.sh fills in the Runtime profile and runs box run in /tmp/box/workspace. If box fails or the agent does not answer within 22s, it serves main.py without box (the Runtime allows 30s). BOX_START_DISABLE=1 skips box.
• Staging on build and deploy: CdkBackend stages <codeLocation>/.box-dist/ before synth, so the zip carries box. The stage includes box, its helpers, its packs, the libffi shim, and the Runtime profile, all from AGENTCORE_BOX_SOURCE (a staging-boxy checkout's target-al2023/). If that variable is unset for a boxed runtime, build fails with an actionable error.
• Runtime box profile: renderRuntimeBoxProfile renders the profile from agentcore.json. It has no reload. Bedrock is signed with a bare aws://, the default chain, which resolves to the execution role. Its placeholders (@CODE@, @PYTHON@, @PYTHON_PREFIX@, @GATEWAY_BOX_URL@, # @AGENT_ENV@) are filled in by start.sh. Only the deployed Memory/Gateway IDs and URLs reach the agent's env. A non-Bedrock provider gets no route yet, because on the Runtime its key comes from AgentCore Identity.
• Memory through the Box gateway: when a boxed runtime has its default Memory, build and deploy add the agentcore passthrough target (bedrock-agentcore.us-west-2, signed with the gateway role) to that runtime's own Box gateway, <runtime>-box, recreating the entry if it was removed. An agentcore target on a non-Box gateway is an error. They also write agentcore/box-memory-policy.json and list it in that gateway's new additionalPolicies. The raw agentcore.json is patched, so unknown fields survive. A second run changes nothing.
• Schema: agentCoreGateways[].additionalPolicies, which cannot be combined with executionRoleArn.
• dev guard: a runtime whose entry point is start.py but has no .box/profile.toml is refused, because start.py runs no agent of its own.

The local (agentcore dev) profile is byte-identical to #2788's for every template and model provider.

Depends on

• feat(dev): Run CodeZip and container agents with box run #2790 (base of this PR), which is stacked on feat(create): Write a box profile for each Python template #2788
• feat(create): Declare the Bedrock target on the runtime's Box gateway #2789, merged into this branch (a5a5a81b, then f98580fe for its latest commits) until it lands, so the diff shows its commits for now. Conflicts are resolved as in box-integration-development (71f93924): DEFAULT_EGRESS_BEDROCK_REGION → BOX_GATEWAY_BEDROCK_REGION, and the Memory target moves from the single box gateway to each runtime's <runtime>-box gateway
• aws/agentcore-l3-cdk-constructs#456: additionalPolicies on the Box gateway role. It is not released or pinned yet
• aws/agentcore-l3-cdk-constructs#454: one Box gateway per runtime (<runtime>-box), which this PR now follows
• A Linux box build via AGENTCORE_BOX_SOURCE, until box ships a Linux release

Related Issue

N/A (box integration)

Documentation PR

Not applicable.

Type of Change

• New feature

Testing

• I ran bun test. The only failures also fail on an unmodified base on this host: toolAvailable, requireTool, SourceResolver bytes ... under node. The migrate tests timed out once under load and pass when run alone
• bun run test:e2e: not run. It needs AGENTCORE_BOX_SOURCE and the unreleased CDK library
• I ran bun run typecheck, lint:check, format:check, audit, secrets:check, build
• I modified src/assets/ and updated manager.test.ts.snap (start.py/start.sh, entrypoint: start.py)
• This PR does not change command.md

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• 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.

[leo237]

Review of the deploy-CodeZip part of this stack (commit 4211fe1 and the merge resolution). I ran the new and changed unit tests locally (boxCodeZip, boxMemory, boxProfile, dev/box, gateway schema): 88 pass. I also checked the L3 CodeZip packager: it does not exclude .box-dist/, and it keeps the exec bit, so the staged box binary ships and runs.

Findings:

1. High: the Memory route only works in us-west-2. The agentcore passthrough target, the route's destinations, and the SigV4 region of the route to the gateway all use BOX_GATEWAY_BEDROCK_REGION. A Memory is a regional resource, and the agent's Memory client calls bedrock-agentcore.<AWS_REGION>. So a deploy to any other region either matches no route or reaches the wrong region's data plane. The policy file's * region suggests every region was meant to work. (inline)
2. High (design): start.sh fails open. If box fails to start, or the agent in it takes longer than 22s to answer, main.py runs without the box. It still holds the full execution role and has unrestricted egress, and the only sign is one [box] FALLBACK log line. The design doc treats the box as the containment boundary, and the security notes from the 10/28 meeting stress telling customers exactly what the box does and does not give them. Falling back silently to no containment works against that. Please consider failing closed by default and making the fallback opt-in. (inline)
3. Medium: port race in the timeout fallback. After kill "$pid" the script does not wait, so main.py can try to bind the ingress port while box still holds it, and box's own agent child may be left running. (inline)
4. Medium (design question): Bedrock skips the Box gateway on the Runtime. The Runtime profile signs Bedrock calls straight from the microVM with the execution role. The bedrock target that create puts on <runtime>-box is then never used on the Runtime, and the execution role needs bedrock:InvokeModel. That conflicts with the design ("egress calls that need credentials leave the microVM"), and it is inconsistent with Memory, which this PR routes through the gateway. If this is a deliberate RIV shortcut, please say so in the code comment. (inline)
5. Low: start.sh has no tests. Nothing tests the placeholder fill-in, the # @AGENT_ENV@ substitution and the env allowlist regex, or the fallback paths. A small bash-driven test with a fake box binary would cover the logic most likely to regress. A missing AGENTCORE_GATEWAY_BOX_URL also fails silently today: the Memory backend URL becomes /agentcore. A warning there would help.

One more thing to keep in mind for merge order: every Python CodeZip project that create makes now has the entrypoint start.py. Once this stack reaches main, agentcore deploy refuses to deploy those projects unless AGENTCORE_BOX_SOURCE is set.

— 🤖 Abhilash's Claude Bot

[leo237]

High: the Memory route is tied to us-west-2. destinations is bedrock-agentcore.us-west-2.amazonaws.com (via BOX_GATEWAY_AGENTCORE_HOST), and the gateway call is signed for us-west-2. On the Runtime, the agent's Memory client calls bedrock-agentcore.<AWS_REGION>, and both the Memory and the <runtime>-box gateway live in the deploy region. A deploy to us-east-1 (for example) then has no route for the agent's Memory calls, and the SigV4 region is wrong for the gateway. The us-west-2 constant is a stated tradeoff for Bedrock models, but it does not carry over to a regional resource like Memory. Suggestion: have start.sh fill in the region from AWS_REGION with an @REGION@ placeholder, as it does for @GATEWAY_BOX_URL@, and resolve the target endpoint per deploy target. The policy file already uses * for the region.

— 🤖 Abhilash's Claude Bot

[leo237]

Same region problem from the gateway side. This passthrough always forwards to bedrock-agentcore.us-west-2, so a Memory deployed to another region is called on the wrong regional data plane, and the gateway role cannot reach it. This needs to follow the deploy target's region. The CDK library could resolve it, or deploy could write it per target.

— 🤖 Abhilash's Claude Bot

[leo237]

High (design): fails open. Every path here, and the 22s timeout and box run exit paths in start_box, ends in exec python main.py with no box. The agent then runs with the full execution role, unrestricted egress and no Dogwood policy, and the only sign is a single [box] FALLBACK log line. A slow cold start, a bad profile, or a missing .box-dist (for example, a deploy without staging) quietly downgrades a contained agent to an uncontained one. Box is the containment boundary in the architecture doc, and the security notes stress telling customers what the box does and does not give them. Suggest failing closed by default: exit non-zero so the Runtime health check fails visibly. Keep the unboxed fallback behind an explicit opt-in such as BOX_START_FALLBACK=1, the counterpart of BOX_START_DISABLE.

— 🤖 Abhilash's Claude Bot

[leo237]

Medium: port race. kill "$pid" sends SIGTERM but does not wait, so serve_without_box execs main.py right away. Box opened the ingress port (0.0.0.0:8080 for HTTP) before the agent was up, and main.py binds that same port. If box has not closed its listener yet, the fallback dies with EADDRINUSE and the Runtime gets nothing. The agent child that box started on the workload port may also outlive box. Suggest kill "$pid"; wait "$pid" 2>/dev/null with a short bounded wait, escalating to kill -KILL if needed. That matters even more if finding 2 keeps any fallback.

— 🤖 Abhilash's Claude Bot

[leo237]

Design question. On the Runtime, Bedrock is signed inside the microVM with the execution role and does not go through the <runtime>-box gateway's bedrock target, which create still declares. Memory, by contrast, goes through the gateway in this PR. The architecture doc says credentialed egress leaves the microVM for the gateway, and instance credentials are used only to invoke the gateway. As written, the execution role needs bedrock:InvokeModel, and the gateway's bedrock target is unused on the Runtime. If this is a deliberate shortcut for now, please say so in this comment and track the follow-up. Otherwise this route should point at ${GATEWAY_BOX_URL}/bedrock, as the Memory route does.

— 🤖 Abhilash's Claude Bot