Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
c6bb00b
fix(box): Keep a host reachable when two path tests of one permit hol…
Nov 20, 2026
acd1419
fix(box): Accept a field that an action test keeps from the action
Nov 20, 2026
daeec2a
fix(box): Name a connection permit that limits the address among the …
Nov 20, 2026
ec299b7
fix(box): Refuse a rule that names a port out of the range 1 to 65535
Nov 20, 2026
f93f4e7
fix(box): Name the right folder in the uv sync hint, and remove the c…
Nov 20, 2026
ddd1408
fix(box): Give a Runtime route a free name when a rule of the policy …
Nov 20, 2026
47acc2f
fix(box): Take one API key credential for its own variable and one ot…
Nov 20, 2026
d0f9523
fix(box): Warn for a host that gets no gateway target, and give a mod…
Nov 20, 2026
662b2ea
refactor(box): Refuse two box runtimes in one folder in the schema, a…
Nov 20, 2026
8942a80
fix(box): Own only the gateway targets that build recorded, and keep …
Nov 20, 2026
c065a0a
test(box): Compare the warning host exactly, for the CodeQL URL check
Nov 20, 2026
2d3ef4a
test(box): Test pathTest and findPath directly, for the review commen…
Nov 20, 2026
40116bd
fix(box): Warn for each egress- target that the one-time migration ke…
Nov 20, 2026
0628b15
docs(box): Say to commit agentcore/box-gateway-targets.json, for the …
Nov 20, 2026
4170b54
fix(box): Read each condition after a temporal or guardrails conditio…
Nov 20, 2026
460c7c9
fix(box): Write an empty record entry for each new Box gateway in cre…
Nov 20, 2026
a8116af
fix(box): Plan the credential of each route and variable that the run…
Nov 20, 2026
36cae3b
fix(box): Say to build again for the variable of a credential that th…
Nov 20, 2026
8b47d0d
refactor(box): Run the credential planner once, and read the record a…
Nov 20, 2026
54e25ad
refactor(box): Replace the two entity casts with one type predicate, …
Nov 20, 2026
065825a
docs(box): Say when to edit agentcore/box-gateway-targets.json, for t…
Nov 20, 2026
8550a46
Merge remote-tracking branch 'upstream/box-integration' into sa/revie…
Nov 20, 2026
808e9c4
test(box): Test a guardrails condition beside the temporal one, for t…
Nov 21, 2026
df61acb
test(box): Drop the unused column of the rotated key test, for the re…
Nov 21, 2026
25a3faa
test(box): Compare the whole host or host:port of a warning, for the …
Nov 21, 2026
33ca203
Merge remote-tracking branch 'upstream/box-integration' into sa/revie…
Nov 21, 2026
854efbd
refactor(box): Keep the targets build owns in one function, for the C…
Nov 21, 2026
adad22d
fix(box): Drop the record entry of each Box gateway that remove runti…
Nov 21, 2026
298dac8
docs(box): Say that build provisions a model-provider key from the sh…
Nov 21, 2026
006f4ba
fix(box): Give equal path patterns one machine, for the Chorus nit on…
Nov 21, 2026
e6b17cb
Merge remote-tracking branch 'upstream/box-integration' into sa/revie…
Nov 21, 2026
f43a55a
fix(box): Keep the record and agentcore.json the same when either wri…
Nov 21, 2026
6596b31
fix(box): Change the record in commitSpec, after remove all removes i…
Nov 21, 2026
eb8673a
test(box): Make the record write fail through an injected writer on e…
Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,10 @@ flags: for templates that take a model provider (`agent-python-strands` and its
variant, `a2a-python-strands`, `agui-python-strands`, `agent-typescript-strands`) the wizard asks
for the provider (Amazon Bedrock, Anthropic, OpenAI, an OpenAI-compatible endpoint, Gemini, or
LiteLLM, which is Python-only), the model id, and an API-key file. The API key is kept in
`agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy.
`agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy. For a Box
template created with no API key, build reads the provider's key (such as `OPENAI_API_KEY`) from
your shell or `agentcore/.env.local`, adds a credential such as `openai`, and deploy provisions
that key in AgentCore Identity.

To bring your own code into a project instead, add a runtime for it:

Expand Down
26 changes: 20 additions & 6 deletions docs/box-local-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,15 +206,29 @@ build context, and write a copy of the profile, the generated packs, and the pol
Box `0.1.11-linux-preview.7` names its packs `@box/base`, `@box/bedrock`, and `@box/agentcore`.
A profile that names a pack `box/<name>` fails: box refuses it and names the `@box/<name>` pack.

- **Gateway targets.** Each host or `host:port` that an `[egress]` entry, an `[mcp]` server
with `type = "http"`, or a policy permit names, and that the policy allows at least one
request to, gets one passthrough target on `<runtime>-box-egress`. The target of an MCP server is
- **Gateway targets.** Each host or `host:port` that an `[egress]` entry, an `[mcp]` server with
`type = "http"`, or a policy permit names, and that the policy allows at least one request to,
gets one passthrough target on `<runtime>-box-egress`. The target of an MCP server is
`egress-<server>`. Its `protocolType` is `CUSTOM`, thus only Box makes the decision on each
`mcp:call`. A host the gateway already has a target for keeps that target. Build owns
only the targets whose name starts with `egress-`: it adds them, changes them, and removes
one when no host needs it. It never changes another target.
`mcp:call`. A host the gateway already has a target for keeps that target. Build owns only the
targets it wrote, which it lists in `agentcore/box-gateway-targets.json`: it adds them, changes
them, and removes one when no host needs it. It never changes another target, also one whose name
starts with `egress-`. `agentcore create` and `agentcore add runtime` write an empty entry for
each new Box gateway, so build owns none of its targets until it writes one. For a gateway that
the file does not list, which an older CLI made, build takes each `egress-` target that has the
shape it writes as its own, once, and warns for each other `egress-` target, which it keeps as
yours. Commit `agentcore/box-gateway-targets.json` with `agentcore.json`: in a clone without it,
build goes back to that `egress-` rule, and can take or give up the wrong targets. The
`.gitignore` that `agentcore create` writes does not exclude it. Build writes the file, but you
edit it in one case: when you change a target that build wrote, build stops and tells you to
remove that target's name from the file to keep the target as yours. Then build no longer records,
changes, or removes it.
- **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret
sends an API key from AgentCore Identity, and an entry with no secret sends no credential.
This includes the model-provider route that `agentcore create` writes when you give it no key,
such as `[egress.openai]` with `env://OPENAI_API_KEY` (also for Anthropic and Gemini). When that
key is set in your shell or in `agentcore/.env.local`, build adds an API key credential such as
`openai`, and deploy provisions your key in AgentCore Identity.
- **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard
host, a plain-HTTP-only host, an unsupported secret, an MCP server that names more than one
host, a path, or a port other than 443, and similar cases stop them too. The error starts with `Build stopped:` or `Deploy stopped:` and the
Expand Down
1 change: 1 addition & 0 deletions src/core/project/backends/boxCodeZip.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,7 @@ function model(policyFiles: string[], runtime = "agent"): BoxNetwork {
region: "us-west-2",
hosts: [],
envRoutes: [],
managedTargets: new Set<string>(),
policyFiles,
runtimeProfile: runtimeProfileOf(policyFiles, runtime),
runtimeProfileHeader: [`Derived from .box/${runtime}/local/profile.toml.`],
Expand Down
21 changes: 5 additions & 16 deletions src/core/project/backends/boxCodeZip.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,9 @@ import { chmodSync, copyFileSync, cpSync, mkdirSync, rmSync, writeFileSync } fro
import { join, posix } from "node:path";
import type { Project } from "../../../handlers/project/types";
import type { BoxNetwork } from "../boxNetwork";
import {
boxNetworkEdits,
runtimeProfileWriter,
writeBoxNetworkFiles,
writeRenderedBoxFiles,
} from "../boxNetworkWriters";
import { BOX_CODEZIP_DIST, runtimeRunsInBox } from "../templates/boxProfile";
import { BOX_BINARIES, type BoxLinuxBuild } from "./boxRelease";
import { stagedRuntimeProfiles } from "./boxStaging";

/** The `.gitignore` staged into `.box-dist/`: build and deploy rewrite the folder every time. */
export const BOX_DIST_GITIGNORE =
Expand Down Expand Up @@ -40,21 +35,16 @@ export async function stageBoxCodeZip(
// @box/agentcore and @box/agentcore-codezip packs.
kind: "codezip" as const,
}));
const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, {
spec: project.spec,
projectRoot: project.rootPath,
env: {},
envLocal: {},
});
const filesOf = (dist: string) => files.filter(({ path }) => path.startsWith(`${dist}/`));
const writeProfile = stagedRuntimeProfiles(project, networks, staged);
// One build for each box version the runtimes name, so each downloads once.
const builds = new Map<string | undefined, BoxLinuxBuild>();
for (const runtime of runtimes) {
const version = runtime.box?.version;
if (!builds.has(version)) builds.set(version, await box(version));
}

for (const { runtime, dist } of staged) {
for (const stage of staged) {
const { runtime, dist } = stage;
const entry = runtimes.find(({ name }) => name === runtime)!;
const build = builds.get(entry.box?.version)!;
const folder = join(project.rootPath, ...dist.split("/"));
Expand All @@ -68,8 +58,7 @@ export async function stageBoxCodeZip(
chmodSync(join(folder, binary), 0o755);
}
cpSync(build.resources, join(folder, "resources"), { recursive: true });
writeBoxNetworkFiles(project.rootPath, filesOf(dist));
writeRenderedBoxFiles(project.rootPath, runtime, dist, filesOf(dist));
writeProfile(stage);
}
return runtimes.map((runtime) => runtime.name);
}
1 change: 1 addition & 0 deletions src/core/project/backends/boxContainer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ function model(policyFiles: string[]): BoxNetwork {
region: "us-west-2",
hosts: [],
envRoutes: [],
managedTargets: new Set<string>(),
policyFiles,
runtimeProfile: {
packs: ["@box/base", "@box/agentcore"],
Expand Down
23 changes: 5 additions & 18 deletions src/core/project/backends/boxContainer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,10 @@ import { dirname, join, posix } from "node:path";
import type { Project } from "../../../handlers/project/types";
import type { ProjectRuntime } from "../../../projectSchemas/runtime";
import type { BoxNetwork } from "../boxNetwork";
import {
boxNetworkEdits,
runtimeProfileWriter,
writeBoxNetworkFiles,
writeRenderedBoxFiles,
} from "../boxNetworkWriters";
import { isFile } from "../runtimeBuild";
import { runtimeRunsInBox } from "../templates/boxProfile";
import type { BoxRelease } from "./boxRelease";
import { assertImageCopiesPolicyFiles } from "./boxStaging";
import { assertImageCopiesPolicyFiles, stagedRuntimeProfiles } from "./boxStaging";

/** The folder a box image's Dockerfile copies its box profile and policy files from. */
export const BOX_IMAGE_DIST = ".box-dist";
Expand Down Expand Up @@ -130,13 +124,7 @@ export async function stageBoxContainers(
dist: posix.join(runtime.buildContextPath ?? runtime.codeLocation, BOX_IMAGE_DIST),
kind: "container" as const,
}));
const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, {
spec: project.spec,
projectRoot: project.rootPath,
env: {},
envLocal: {},
});
const filesOf = (dist: string) => files.filter(({ path }) => path.startsWith(`${dist}/`));
const writeProfile = stagedRuntimeProfiles(project, networks, staged);
for (const runtime of runtimes) {
const policyFiles = networks.find((n) => n.runtime === runtime.name)?.policyFiles ?? [];
assertImageCopiesPolicyFiles(
Expand All @@ -145,15 +133,14 @@ export async function stageBoxContainers(
policyFiles,
);
}
for (const [index, { dist }] of staged.entries()) {
for (const [index, stage] of staged.entries()) {
const runtime = runtimes[index]!;
const folder = join(project.rootPath, ...dist.split("/"));
const folder = join(project.rootPath, ...stage.dist.split("/"));
await rm(folder, { recursive: true, force: true });
await mkdir(folder, { recursive: true });
const release = await releaseFor(runtime.box?.version);
await writeFile(join(folder, BOX_RELEASE_ENV), boxReleaseEnv(release));
writeBoxNetworkFiles(project.rootPath, filesOf(dist));
writeRenderedBoxFiles(project.rootPath, runtime.name, dist, filesOf(dist));
writeProfile(stage);
}
return runtimes.map((runtime) => runtime.name);
}
32 changes: 32 additions & 0 deletions src/core/project/backends/boxStaging.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,39 @@
import { readFileSync } from "node:fs";
import { ProjectStateError } from "../../../errors/errors";
import type { Project } from "../../../handlers/project/types";
import type { BoxNetwork } from "../boxNetwork";
import {
boxNetworkEdits,
runtimeProfileWriter,
writeBoxNetworkFiles,
writeRenderedBoxFiles,
type StagedRuntime,
} from "../boxNetworkWriters";
import { boxLocalProfileFile } from "../templates/boxProfile";

/**
* What the runtime profile writer writes from each runtime's Box network model for the runtimes of
* `staged`, with the function that writes one runtime's files into its staged folder and a copy
* into its `.box/<name>/aws/`.
*/
export function stagedRuntimeProfiles(
project: Project,
networks: readonly BoxNetwork[],
staged: readonly StagedRuntime[],
): (runtime: StagedRuntime) => void {
const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, {
spec: project.spec,
projectRoot: project.rootPath,
env: {},
envLocal: {},
});
return ({ runtime, dist }) => {
const own = files.filter(({ path }) => path.startsWith(`${dist}/`));
writeBoxNetworkFiles(project.rootPath, own);
writeRenderedBoxFiles(project.rootPath, runtime, dist, own);
};
}

/** A `COPY` of the whole staged folder, which takes the policy files in with the profile. */
const COPIES_WHOLE_DIST = /^\s*COPY\s+(?:--\S+\s+)*(?:\.box-dist|\$\{BOX_DIST\})\/?\s/m;

Expand Down
1 change: 1 addition & 0 deletions src/core/project/backends/cdk.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -341,6 +341,7 @@ describe("CdkBackend.build", () => {
region: "us-west-2",
hosts: [],
envRoutes: [],
managedTargets: new Set<string>(),
policyFiles: [],
runtimeProfile,
grantedActions: [],
Expand Down
121 changes: 121 additions & 0 deletions src/core/project/boxGatewayTargets.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
/**
* The record of the targets that build writes for each Box gateway, by the gateway's name. Build
* owns those targets, and no other. `agentcore create` and `agentcore add runtime` write an empty
* entry for each new Box gateway, so the `egress-` rule applies only to a gateway an older CLI made.
*/
import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { z } from "zod";
import { ProjectStateError } from "../../errors/errors";

/** The record's name in the `agentcore/` folder. */
export const BOX_GATEWAY_TARGETS_NAME = "box-gateway-targets.json";

/** The record's path from the project root. */
export const BOX_GATEWAY_TARGETS_FILE = `agentcore/${BOX_GATEWAY_TARGETS_NAME}`;

const BoxGatewayTargetsSchema = z.record(z.string(), z.array(z.string()));

/** The record as a file holds it. */
export function boxGatewayTargetsText(record: Readonly<Record<string, readonly string[]>>): string {
return `${JSON.stringify(record, undefined, 2)}\n`;
}

/**
* The targets build wrote for each Box gateway, or `undefined` when the project has no record.
* Throws for a file that is not the record.
*/
export function readBoxGatewayTargets(projectRoot: string): Record<string, string[]> | undefined {
const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/"));
if (!existsSync(path)) return undefined;
let document: unknown;
try {
document = JSON.parse(readFileSync(path, "utf8"));
} catch {
document = undefined;
}
const record = BoxGatewayTargetsSchema.safeParse(document);
if (record.success) return record.data;
throw new ProjectStateError(
`${BOX_GATEWAY_TARGETS_FILE} is not the record of the gateway targets that build writes: a ` +
"JSON object with a list of target names for each Box gateway. Remove the file, and build " +
"writes it again.",
);
}

/** Puts the record back as it was before a change: its old text, or no file. */
export type RestoreRecord = () => void;

/** How the record file is written and removed. */
export interface RecordFiles {
readonly write: (path: string, text: string) => void;
readonly remove: (path: string) => void;
}

/** The record file on disk. */
export const FS_RECORD_FILES: RecordFiles = {
write: (path, text) => writeFileSync(path, text),
remove: (path) => rmSync(path, { force: true }),
};

/**
* Adds an empty entry for each of `gateways` that the record does not name yet. Returns the
* function that puts the record back, when it wrote the record; it leaves a file that is not the
* record to build, which refuses it.
*/
export function addBoxGatewaysToRecord(
projectRoot: string,
gateways: readonly string[],
files: RecordFiles = FS_RECORD_FILES,
): RestoreRecord | undefined {
return changeRecord(projectRoot, files, (record) => {
const added = gateways.filter((gateway) => !Object.hasOwn(record ?? {}, gateway));
if (added.length === 0) return undefined;
return { ...record, ...Object.fromEntries(added.map((gateway) => [gateway, []])) };
});
}

/**
* Removes the entry of each of `gateways` from the record, when the record names it. Returns the
* function that puts the record back, when it wrote the record; it leaves a file that is not the
* record to build, which refuses it.
*/
export function removeBoxGatewaysFromRecord(
projectRoot: string,
gateways: readonly string[],
files: RecordFiles = FS_RECORD_FILES,
): RestoreRecord | undefined {
return changeRecord(projectRoot, files, (record) => {
if (!record || !gateways.some((gateway) => Object.hasOwn(record, gateway))) return undefined;
return Object.fromEntries(
Object.entries(record).filter(([gateway]) => !gateways.includes(gateway)),
);
});
}

/**
* Writes the record that `change` makes of the record, or of no record; `undefined` from `change`
* writes nothing. Returns the function that puts the old text back, or removes the file.
*/
function changeRecord(
projectRoot: string,
files: RecordFiles,
change: (record: Record<string, string[]> | undefined) => Record<string, string[]> | undefined,
): RestoreRecord | undefined {
let record: Record<string, string[]> | undefined;
try {
record = readBoxGatewayTargets(projectRoot);
} catch (error) {
if (error instanceof ProjectStateError) return undefined;
throw error;
}
const changed = change(record);
if (changed === undefined) return undefined;
const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/"));
const before = record === undefined ? undefined : readFileSync(path, "utf8");
files.write(path, boxGatewayTargetsText(changed));
return () => {
if (before === undefined) files.remove(path);
else files.write(path, before);
};
}
Loading
Loading