Managed tools and environments

Platform administrators control the software available inside intent runtimes. The platform ships one protected Standard environment and a catalog of tool definitions. Administrators publish exact tool versions, compose those versions into environments, and publish environment revisions that space owners can assign.

Standard provides the protected AgentCore runtime plus Node.js and Python. It also includes MarkItDown for agents to extract text and tables from PDF, DOCX, and XLSX files already present in their workspace. Agents invoke markitdown path/to/document.pdf when needed; the platform does not run an automatic conversion step.

Java, Go, Rust, Maven, and Gradle are shipped as tool definitions, not as predefined JVM, Go, Rust, or Polyglot environments. Administrators can add other tools, such as a .NET SDK, without changing the application source.

Quick start

Choose the path that matches your task:

The normal flow is:

flowchart LR
    T["Publish exact tool versions"] --> E["Build an environment revision"]
    S["Standard<br/>Node.js + Python"] --> E
    E --> P["Publish the environment"]
    P --> A["Assign it to a space"]
    A --> I["Create an intent<br/>runtime snapshot is pinned"]

Publishing a newer tool or environment revision never changes an existing intent. New intents snapshot the currently published revision of the space-assigned environment.

Detailed guide

Access and responsibilities

The managed build views are under Admin -> Environments and require the platform-admin role:

• Tools imports, builds, verifies, publishes, and recommends tool versions.
• Environments composes published tool versions into runtime images.

Space Owners and Admins select a published environment under Space Settings -> Environment. Space Members can see the assignment but cannot change it.

The object model

The important invariants are:

• Only published tool versions can be added to an environment.
• Only a READY tool version or environment revision can be published.
• Published tool versions and environment revisions are immutable.
• Publishing or recommending a tool version never rewrites an existing environment revision.
• Publishing a new environment revision affects new intents for assigned spaces. Existing intents stay pinned to their original runtime target.

Shipped tool definitions

The catalog bootstrap creates these tool families and initial version definitions:

The scheduled bootstrap queues independent initial versions for import. Maven and Gradle remain drafts until Java has a published recommended version because their own functional checks require Java.

On a deployment that publishes the x86_64 core image (Instances compute enabled), the bootstrap also creates an x86_64 version of each of the five tools, next to the arm64 one, and starts the Java, Go, and Rust x86_64 builds. Nothing is published or recommended automatically: the x86_64 versions wait for the same build, review, publish, and recommend steps as the arm64 ones, and x86_64 Maven and Gradle stay drafts until x86_64 Java is published and recommended. See x86_64 tool versions.

These are catalog entries only. They do not create space-selectable environments by themselves.

Tool-version lifecycle

The Tools workspace shows a visual path for every selected version:

Define -> Build -> Check -> Publish -> Recommend

The active step includes a waiting indicator while CodeBuild or ECR is still working. CodeBuild logs are available as soon as the build supplies a log URL, and Open ECR is available after the image exists.

Refreshing the browser is not required while a build is active; the view polls the version until it reaches a reviewable or terminal status.

Add a new tool

Prepare the source

Before opening the form, identify:

• An exact version.
• The architecture, arm64 or x86_64. The architecture choice appears only when the deployment publishes the x86_64 core image; otherwise every version is arm64.
• The publisher's official Linux archive URL for that architecture.
• The distribution and publisher, for example Amazon Corretto and Amazon Web Services.
• The tool type, such as Java JDK, Go SDK, or Other CLI.

For the normal case, that is all the version form requires. The tool type supplies the executable paths, environment variables, dependencies, version command, and functional check. Open Advanced options only for an unusual archive layout, installer, dependency, package prerequisite, or verification command.

The optional advanced checksum fields can record a publisher-provided checksum and public checksum-evidence URL. The platform always pins the downloaded artifact to its calculated SHA-256 even when those fields are empty.

The import path accepts public HTTPS archives ending in:

• .tar.gz
• .tgz
• .tar.xz
• .zip

The source URL must not contain credentials, query parameters, fragments, or embedded secrets. The platform rejects private, local, link-local, and metadata-service destinations. The source download is bounded, redirects are revalidated, and the archive is checked for traversal paths, unsafe links, special files, excessive entry counts, and excessive expanded size.

Source uploads are not supported. Tool definitions import from public HTTPS URLs so the retained source has an auditable publisher location.

Current import limits are:

Create the family and first version

1. Open Admin -> Environments -> Tools.
2. Choose New tool family.
3. Enter a human-readable Name, for example .NET SDK.
4. Enter or accept the stable lowercase ID, for example dotnet-sdk.
5. Enter the Publisher, Category, and Description.
6. Enter the Exact version.
7. Select the Tool type.
8. Select the Architecture when offered. It defaults to arm64.
9. Enter the Linux ARM64 download URL (or Linux x86_64 download URL).
10. Choose Create and start build.

Creating the family and creating its first version happen together. A tool family can later contain multiple published versions. For the first version, the family name and publisher are also used as the distribution identity.

The tool ID is a durable catalog key. Do not include the version in it. Use dotnet-sdk, not dotnet-sdk-8. The version belongs to the tool-version record.

Choose a tool type

Tool types fill in executable paths, environment variables, dependencies, the version command, and a representative functional check:

Selecting a tool type is a starting point, not a bypass. Review the generated executable paths and expected version before building.

Publisher checksum and source trust

The publisher checksum section is optional. Supply both:

• A SHA-256 or SHA-512 digest published by the vendor.
• A public evidence URL from which the platform can independently find that digest.

The catalog displays:

• Publisher verified when the downloaded archive matches the supplied publisher digest and the digest is also found at the independently fetched evidence URL.
• Platform pinned when the platform computed and retained its own SHA-256 digest but no independently verified publisher evidence was supplied.

Both trust levels pin the imported source and resulting OCI artifact by digest. Publisher verified adds independent evidence about who published the source.

The first successful source import is retained under its digest. Retrying an installer or verifier correction reuses that retained source instead of silently downloading a new archive.

Generated archive installation

Use generated installation whenever the archive already contains the desired tool layout.

Set Root folders to remove to the number of wrapper directories that should be removed during extraction. For example, an archive containing tool-1.2.3/bin/tool needs one root folder removed when bin/tool should be at the normalized tool root.

Generated installation extracts the verified archive without executing publisher-supplied installation code.

Custom installation

Enable the custom installer only when extraction is insufficient. The Bash script receives:

• TOOL_SOURCE: the read-only retained source archive.
• TOOL_OUTPUT: the writable directory that must contain the normalized tool.
• TOOL_ARCHIVE_FORMAT: the detected source format.

The installer runs inside a nested container with:

• No AWS credentials.
• No EC2 or ECS metadata access.
• No Docker socket.
• No host mounts other than the retained source and output directory.
• No access to private or link-local networks.
• Bounded CPU, memory, process count, temporary storage, and output size.

Public internet access is available to the installer. If the script downloads additional mutable content, the published OCI digest remains immutable and verified, but rerunning the script is not guaranteed to produce the same artifact. Prefer the retained source archive and exact checksums whenever possible.

Do not put credentials or secrets in installer scripts. The API rejects common secret patterns, and definitions are visible to platform administrators.

Executables and dependencies

Under Executables, dependencies, and custom verification:

• List each executable as name=relative/path, for example dotnet=dotnet or java=bin/java.
• Select another tool family when this tool cannot be verified or used without it.
• Add required Debian packages as package=exact-version.
• Add non-secret variables as NAME=value.
• Use ${TOOL_ROOT} when a variable should point at the normalized tool root.

A dependency resolves to that family's published recommended version for the same architecture. A dependent version cannot build until every dependency has a published recommended version of that architecture (TOOL_RECOMMENDED_DEPENDENCY_MISSING), and a dependency of the other architecture is rejected (TOOL_ARCHITECTURE_MISMATCH). The platform rejects missing families, self-dependencies, dependency cycles, executable collisions, package-version conflicts, and environment-variable conflicts.

Custom verification

Every version requires a version command and expected output. Use the optional networkless verifier for additional behavior that the selected preset does not cover.

The verifier:

• Runs as the non-root runtime user.
• Has no network access.
• Uses isolated writable caches for SDKs and build tools.
• Can read up to 32 text fixture files supplied in the form.
• Receives fixture files read-only.
• Must complete within the build's resource and time limits.

Use fixture files for a minimal real project, configuration file, or expected output. Do not include credentials or production data.

Example: add a .NET SDK

1. Choose New tool family.
2. Set Name to .NET SDK and ID to dotnet-sdk.
3. Set Publisher to Microsoft and Category to Language SDK.
4. Enter the exact SDK version.
5. Select the .NET SDK tool type.
6. Enter Microsoft's official Linux ARM64 SDK archive URL (or the x64 archive, with Architecture set to x86_64).
7. Choose Create and start build.
8. Review the source, artifact, package inspection, and functional check.
9. Publish the version.
10. Make it recommended if it should be the default .NET SDK for new environment drafts.

This adds .NET as a selectable tool. It does not create or publish a .NET environment automatically.

What a tool build verifies

A successful CodeBuild job is only one part of the tool decision. The catalog records evidence for:

1. Source import: validated public URL, resolved redirects, source size, platform SHA-256, and optional publisher evidence.
2. Archive safety: bounded entry count and expanded size, safe relative paths, safe links, and no special files.
3. Installation: generated extraction or sandboxed installer output.
4. Artifact normalization: executable paths exist, symlinks remain inside the tool root, and output stays within the tool-artifact size limit.
5. OCI publication: an immutable tool image and digest for the version's architecture. The build checks that the image architecture matches.
6. SBOM: an SPDX document generated from the normalized payload.
7. Security scan: ECR findings with severity, advisory, package, and package version where available, or a recorded administrator decision when ECR cannot scan the normalized artifact.
8. Runtime compatibility: the protected core digest and compatibility version used for verification.
9. Version check: the configured command contains the exact expected output.
10. Functional check: the selected preset and optional custom verifier run as the non-root runtime user.

The Tools view retains the source digest, trust level, official source link, artifact digest, compressed size, runtime contract, findings, acceptance identity, failure detail, and CodeBuild logs.

Review failures and security findings

Build or verification failure

For a FAILED version:

1. Open CodeBuild logs and read the field-specific failure detail shown in the version.
2. Choose Edit when the archive layout, executable path, installer, package, variable, version command, or verifier is wrong.
3. Choose Save and rebuild to store the corrected definition and queue a new build.
4. Choose Retry only when the definition is already correct and the failure was transient.

The exact version string cannot be changed while editing. Create a new version when the version number changes.

Security review

Critical or High ECR findings move the version to SECURITY_REVIEW; they do not erase a successful artifact build. ECR Basic scanning cannot inspect some normalized artifacts that intentionally contain no operating-system package database. Those versions also move to SECURITY_REVIEW with the scanner limitation retained as evidence.

The administrator can:

• Leave the version unpublished and remediate its source or dependencies.
• Choose Review package findings when Critical or High package findings were detected, then explicitly continue to record the decision and move the version to READY.
• Choose Continue without scan when ECR cannot inspect the artifact format. The dialog explains that this is a scanner limitation, not a detected vulnerability.

Acceptance does not publish the version. The findings and acceptance record remain visible after publication and in every environment revision that snapshots that tool version.

Publish and recommend tools

Publishing and recommending are separate decisions:

Multiple versions of the same tool can remain published. Each architecture has its own recommendation: one arm64 version and one x86_64 version per tool family. Make recommended on an x86_64 version sets only the x86_64 recommendation, and the other way round.

Publishing a newer version does not automatically recommend it. Recommending a new version:

• Changes the version selected when an administrator first enables that tool in an environment editor.
• Changes the dependency version automatically selected for tools such as Maven or Gradle.
• Marks affected environments of the same architecture with a tool-update warning. An x86_64 recommendation never flags arm64 environments.
• Does not change an existing environment revision.
• Does not change an active or completed intent.

Choosing Replace recommendation directly replaces the current recommended version within that tool family. The existing recommendation does not need to be removed first.

For shipped tools, publish and recommend Java before building Maven or Gradle. This applies per architecture: x86_64 Maven and Gradle can only build once x86_64 Java is published and recommended.

Add or update a tool version

To add a newer version or another distribution:

1. Open the tool family in Admin -> Environments -> Tools.
2. Choose Add distribution or version.
3. Enter the distribution, publisher, exact version, architecture (when offered), and the Linux download URL for that architecture. The existing family supplies the tool type.
4. Choose Create and start build.
5. Review the lifecycle and evidence.
6. Publish the version.
7. Choose Make recommended or Replace recommendation only when the new version should become the default.

The prior published version remains selectable. Environments pinned to it remain valid.

For example, add Amazon Corretto as another version in the existing Java JDK family. Set Distribution to Amazon Corretto, Publisher to Amazon Web Services, choose the exact Corretto version and archive, then publish and replace the Eclipse Temurin recommendation if Corretto should become the default. Both distributions remain selectable.

To correct an unpublished version, use Edit while its status is DRAFT or FAILED. Published versions cannot be edited; create another version instead.

x86_64 tool versions

x86_64 tool versions exist only on deployments that publish the x86_64 core image, which enable_instances_compute provides (see Compute types). Without it the Architecture field and the Add x86_64 build action are hidden, and the API rejects x86_64 builds with AMD64_CORE_IMAGE_MISSING.

Each architecture is a separate tool version of the same family, with its own download, checksum, build, security review, publication, and recommendation. x86_64 versions build on an x86_64 CodeBuild fleet against the amd64 build of the protected core, and their checks run natively on x86_64.

To add the x86_64 build of a version that exists for arm64:

1. Select the arm64 version in the tool family.
2. Choose Add x86_64 build. The form copies the version, layout, installer, and verification of the arm64 version and clears the download URL and publisher checksum.
3. Enter the publisher's x86_64 archive URL, and its checksum if you record one.
4. Review the installer when the arm64 version uses a custom installer script. A tool-type preset script, such as the Rust installer, is switched to the x86_64 target automatically; a script you edited by hand is copied unchanged and may still contain arm64-specific paths.
5. Choose Create and start build, then review, publish, and recommend the x86_64 version as usual.

An x86_64 environment can only select x86_64 tool versions and an arm64 environment only arm64 versions. x86_64 versions show an x86_64 badge in the version list.

Architecture-related errors:

Select a specific Java, Go, Rust, or other tool version

Tool versions are selected on an environment revision, not globally:

1. Publish every exact version that administrators should be able to use.
2. Open Admin -> Environments -> Environments.
3. Create an environment or open an existing environment.
4. Enable the tool when it is not inherited from the base.
5. Select the exact published version from the version control.
6. Choose Create Draft or Save as New Revision.
7. Build, review, and publish that environment revision.

When a tool has only one published version, the editor shows its version and an Add action; there is no redundant version selector. The tool can be removed again before the revision is saved. A selector appears when:

• More than one published version is available.
• The base already includes the tool and a published version can override the inherited version.

The recommended version is preselected when a tool is enabled. It is a default, not a restriction. Any published version shown by the selector can be chosen.

Create an environment

Open Admin -> Environments -> Environments and choose New environment.

1. Enter a name and description. Optionally provide a stable environment ID; otherwise one is generated from the name.
2. Select a published Base environment. Use Standard unless the new environment intentionally extends another published custom environment.
3. Review the protected Node.js and Python versions and any tools inherited from the base.
4. Search or browse the tool catalog and choose Add for each capability. The recommended published version is selected initially.
5. Use the version selector when multiple published versions exist or when overriding a tool inherited from the base.
6. Review dependencies marked Required or Automatic. They are added at their recommended published versions.
7. Expand Advanced settings only when catalog tools do not cover the need. Add exact apt packages, non-secret environment variables, or restricted single-line build commands as structured rows.
8. Review the live Composition summary and projected compressed size. AgentCore runtime images must remain at or below 2048 MiB.
9. Choose Create draft.
10. Open Revisions, select the draft revision, and choose Build.

Environment variables and build commands cannot replace protected runtime behavior, inject secrets, change the runtime user, entrypoint, command, port, or health contract, or overwrite protected platform variables.

Compute types: microVMs and Instances

The compute type decides where and how an environment's agent sessions run:

• microVMs (default) — serverless AgentCore microVMs with managed session storage (1 GiB at /mnt/workspace), billed per session.
• Instances — EC2 managed instances in the platform account, provisioned through AgentCore capacity providers, with a persistent EBS workspace volume per session, account-level controls (Savings Plans, ODCRs, data stays in-account) and sessions of up to 14 days.

The architecture (arm64 or x86_64) is a separate choice: it decides which image is built and which catalog tool builds apply, independently of where the image runs.

An environment's compute is the pair { type, architecture } — the compute type (microvms | instances) and the CPU architecture (arm64 | x86_64) are independent axes. Which combinations a deployment can build and run is exposed by GET /environments/capabilities as a matrix (combinations[].{type, architecture, available, reason?, allowedInstanceTypes?}), and the Compute selector renders exactly the available cells. Today the matrix is:

Enable it on the deployment

The compute type is opt-in per deployment:

enable_instances_compute = true

# Optional overrides (these are the defaults)
instances_allowed_instance_types       = ["m6i.large"] # x86_64; burstable (t-family) is not supported
instances_allowed_instance_types_arm64 = ["m7g.large"] # arm64 (Graviton); [] disables arm64 Instances
instances_workspace_gib                = 50

Enabling the flag provisions the x86_64 (amd64) build of the platform core image and the VPC wiring the instances attach to, and grants the status lambda the capacity-provider provisioning permissions. The Terraform variables are the only source of this configuration: both the API (capability matrix and draft validation) and the status poller (capacity-provider creation) read the same values, and the Lambda code has no defaults of its own. When the flag is off (the default), the Instances cells are unavailable in the capability matrix, the compute selector only offers microVMs, and the API rejects Instances drafts with INSTANCES_COMPUTE_NOT_CONFIGURED.

Turning the flag off again after Instances environments have been used does not destroy anything that live runtimes depend on: the capacity-provider operator role is created unconditionally (capacity providers are retained and keep referencing it), and existing capacity providers, runtimes, and published revisions are left in place. New Instances drafts are refused, and no new image build of an existing Instances environment is admitted until the flag is re-enabled (see below). Workspace cleanup is not gated by the flag: the poller keeps its DeleteCapacityProviderSession permission, so queued releases still complete and intents on retained Instances runtimes can still be deleted. An instance family is built for one architecture only, so each architecture has its own allowlist; the capability matrix reports the list per cell, and an architecture whose list is empty is reported as NO_INSTANCE_TYPES and cannot be selected. Changing an allowlist or instances_workspace_gib produces a new capacity provider on the next runtime creation; runtimes created earlier keep the provider they were built with.

Build admission. Every new image build of an existing environment — Build, Retry, Rebuild and the bulk rebuild — is checked against the same capability matrix before anything is created: if the environment's compute cell is unavailable on the deployment (flag off, its architecture's allowlist empty, or the x86_64 core image missing), the request is rejected with the cell's code (INSTANCES_COMPUTE_NOT_CONFIGURED, NO_INSTANCE_TYPES, AMD64_CORE_IMAGE_MISSING) and no revision, build context or CodeBuild run is created. A bulk rebuild that names environments explicitly is rejected as a whole and lists the unbuildable ones; the implicit "everything with an update" rebuild skips them and reports them under skipped. Saving a draft is not a build and stays allowed. Admission only gates new builds: published revisions, intents already pinned to a snapshot (including resume and rewind), and workspace cleanup keep working.

Create an Instances environment

With the flag enabled, New environment shows a Compute selector:

• one entry per available cell of the capability matrix, for example Serverless microVMs (arm64), EC2 Instances (arm64) and EC2 Instances (x86_64). Instances entries list the instance types the deployment allows for that architecture.

Both the compute type and the architecture are fixed at creation and cannot be changed afterwards. The architecture — not the compute type — decides which catalog tools and bases apply: an x86_64 environment lists only tool versions with an x86_64 build and derives from Standard (the build swaps in the published core revision's x86_64 image variant) or from another x86_64 environment; an arm64 environment — on either compute type — uses the arm64 builds.

The build, security review, and publish flows are the same on both compute types, with one difference on Instances: runtime validation first has to provision an EC2 instance, so a cold start can take several minutes. The revision stays VERIFYING while the poller re-attaches to the same validation session until the instance is up (bounded by MANAGED_INSTANCES_VALIDATION_MAX_POLLS, 30 polls by default). The poll runs every minute and can outlast that interval, so each revision's verification is leased to one poll at a time; only the lease holder creates, reuses or releases the validation session. The lease holder adopts a session retained by an earlier poll before it does anything else, so every way the validation can end, including a failed endpoint check, releases that session. Ending a validation is recorded before it is irreversible: the outcome is written together with retiring the session id (it is never invoked again), then the session is deleted or queued for cleanup, then the revision becomes READY or FAILED. A poll that finds a recorded outcome finishes it instead of validating again, so a failed write or an interrupted poll never reuses a released session and never loses its cleanup.

Persistent workspaces and cost

Each Instances session attaches a dedicated EBS workspace volume (gp3, instances_workspace_gib, 50 GiB by default) mounted at /mnt/workspace. The volume survives session stops, idle timeouts, and instance lifetimes — an intent can resume exactly where it left off, including across parallel unit lanes, which each get their own session and volume.

Because the volume persists, it also keeps billing until its session is explicitly deleted. The platform distinguishes stopping a session (the compute ends, the workspace is retained and re-attached by the next invocation of the same session id) from releasing it (the workspace is deleted). The volume retention policy is explicit and bound to the intent's lifetime:

A workspace is part of the intent's state for as long as the intent exists: a finished run can be rewound and a parked stage resumed, and both rely on the checkout and conversation state on the volume. On deletion, every session of the intent is stopped and released: the main session, all unit-lane sessions (including lanes from earlier plans), every compose session, the Quorum-edit session and one session per discussion thread. Each of these is derived from a record that exists before the session is first invoked (unit, compose and Quorum-edit rows, discussion threads), so none is missed. The auxiliary sessions are not released earlier because their ids are reused, and a deleted Instances session cannot be started again.

Space-level probes (CLI capabilities, Test on MCP servers and on an agent connection) open a fresh session against the space's environment. On Instances the probe first records its cleanup as durable work, deferred by 15 minutes so the poller does not race the probe, then runs, then deletes the session and removes the record. If the response is lost or the delete fails, the record stays and the poller deletes the session after the deferral. If the record cannot be written, the probe does not run. The fallback authentication qualification never opens a session on Instances: it uses the authentication support the revision's validation recorded, and asks to republish the environment if none was recorded. A release that fails for any reason other than the session already being gone is queued as durable cleanup work (SESSION_CLEANUP# records on the environment registry table) and retried by the environments status poller until the volume is gone — the same mechanism covers validation sessions. Whoever holds a session id keeps it until the release is completed or queued: if queueing itself fails, an intent delete returns 503 with nothing deleted, and a validation stays VERIFYING with its session until the next poll, so the identity of a volume is never dropped.

EC2 instances themselves start on demand and are reclaimed by the capacity provider; you pay for instance time while sessions are active plus EBS storage for volumes of intents that still exist.

What an environment build verifies

The generated Dockerfile:

• Starts from the exact pinned base revision and digest.
• Copies each selected tool from its exact OCI digest.
• Installs exact apt package versions.
• Applies non-secret variables and restricted build commands.
• Restores the protected non-root runtime user.
• Retains the platform-owned runtime files, entrypoint, command, port, and health behavior.

The build then checks:

• The target architecture (arm64, or x86_64 for Instances environments) and the pinned base digest.
• Protected runtime files against the base.
• Non-root execution and writable workspace behavior.
• The generated SPDX SBOM.
• Tool version commands and representative builds.
• Container startup, /ping, shutdown, and runtime invariants.
• Final image size.
• ECR vulnerability findings.
• AgentCore runtime and endpoint creation.
• Capability and deterministic command checks through the created endpoint.

The revision reaches READY only after image validation, the security decision, and AgentCore runtime validation succeed.

Environment-revision lifecycle

The revision workspace shows the process as a visual path:

Define -> Build -> Check -> Verify -> Publish

The active Build, Check, or Verify step displays a waiting indicator. CodeBuild logs are shown when available, and the ECR repository is linked after the image has been created.

The evidence view separates image-build success, security findings, and runtime validation. A successful image can therefore remain visible even when it is waiting for security review or later runtime validation fails.

Publish an environment

Select a READY revision and choose Publish.

Publication atomically moves the environment's published-revision pointer. The previous published revision becomes superseded but remains retained while active intent snapshots reference its runtime artifacts.

After publication:

• The environment appears in Space Settings -> Environment.
• New intents in spaces already assigned to that environment use the newly published revision.
• Existing intents continue using their snapshotted revision and endpoint.
• Draft, failed, and ready revisions do not affect space execution until one is published.

Update an environment

Environment revisions are immutable. Every change creates another draft revision.

Use a newer tool version

1. Publish the new tool version.
2. Recommend it when it should become the default. Affected environments show a recommended-tool update warning.
3. Open the environment.
4. Open Definition and select the desired exact version in the tool list.
5. Review the composition summary and choose Save as new revision.
6. Open Revisions, then build, review, and publish the new revision.

The warning is informational. No revision changes until the administrator selects versions and saves a new revision.

Use a newer base revision

When the published base changes, dependent environments show an update warning. Choose Rebuild on Latest Base to clone the current recipe and change only its pinned base revision.

The rebuilt revision still requires image validation, security review when applicable, runtime validation, and manual publication.

When both base and tool updates are available, edit the environment and use Save as New Revision so the exact tool selections are explicit.

Retry a failed revision

Use Retry only when the same recipe and pinned base are still valid. If a newer base is required or the pinned digest is unavailable, use Rebuild on Latest Base instead.

A failed attempt never replaces the currently published revision and never changes space assignments.

Select an environment for a space

1. Open the space.
2. Open Space Settings -> Environment.
3. Select a published environment.
4. Review its included tools, exact published revision, image digest, and runtime compatibility version.
5. Review repository compatibility warnings.
6. Choose Assign Environment.

Compatibility warnings compare detected repository stacks with the tools in the selected environment. They are advisory; assignment is still allowed.

New spaces are assigned the default environment, which is Standard unless a platform administrator has chosen another.

The assignment stores the environment ID, not a mutable container reference. When an intent is created, the platform resolves that environment's current published revision and snapshots:

• Environment ID and name.
• Revision ID.
• Image digest.
• AgentCore runtime ARN and version.
• Runtime endpoint.
• Runtime compatibility version.
• Verification result.
• Resolved tool versions.

Changing the space assignment affects only intents created afterward. Running, waiting, rewound, cancelled, and resumed intents continue to target their original snapshotted runtime and endpoint.

Choose the environment before creating the intent that should use it.

Set the default environment for new spaces

New spaces use Standard unless a platform administrator chooses another default:

1. Open Admin -> Environments -> Environments.
2. Select a published environment and choose Set as default. A star marks the current default in the list.

To go back to Standard, choose Set as default on Standard.

An environment can only be the default when its published revision passes the same check as intent creation: published, verified, with a runtime and image digest, and on a supported runtime compatibility version. Otherwise the change is refused with the reason.

The default is read when a space is created and stored as that space's assignment, so:

• Existing spaces keep their environment when the default changes.
• Space owners can still assign another environment afterwards.
• If the default stops passing the check later, for example after a platform upgrade raises the runtime compatibility version, new spaces use Standard and the projects Lambda logs a warning. Space creation is never blocked.

The default environment cannot be retired: retiring it returns DEFAULT_ENVIRONMENT. Choose another default first.

Platform administrators can also read and change the setting with GET and PUT /environments/settings/default, using a body of { "environmentId": "<id>" }.

Audit an intent's environment

Intent details and audit output show the immutable environment snapshot used by the run. Use those values when diagnosing a difference between two runs:

• A space may have been reassigned after the older intent was created.
• A newer revision may have been published for the same environment ID.
• A tool recommendation may have changed without that tool version being incorporated into the published environment.

The space setting describes what the next intent will use. The intent snapshot describes what that specific intent actually uses.