feat: add runtime read-only control-plane commands

README.md

@@ -49,6 +49,15 @@ agentcore                          # interactive TUI
 │       ├── list
 │       ├── update
 │       └── delete
+├── runtime                        # inspect deployed AgentCore Runtimes
+│   ├── get                        # fetch a Runtime by id
+│   ├── list                       # list Runtimes (server-side paginated)
+│   ├── version
+│   │   ├── get                    # get a specific Runtime version
+│   │   └── list                   # list a Runtime's versions
+│   └── endpoint
+│       ├── get                    # get a Runtime endpoint by qualifier
+│       └── list                   # list a Runtime's endpoints
 └── config                         # read/write global config values
 ```
 
@@ -84,6 +93,14 @@ agentcore harness invoke --id <harnessId> --session-id <session> --qualifier PRO
 
 # Run a shell command inside the agent runtime
 agentcore harness exec --id <harnessId> --command "ls -la" --json
+
+# Inspect deployed Runtimes without project configuration or deployment
+agentcore runtime get --id <runtimeId>
+agentcore runtime list --max-results 20
+agentcore runtime version get --id <runtimeId> --version <version>
+agentcore runtime version list --id <runtimeId> --max-results 20
+agentcore runtime endpoint get --id <runtimeId> --qualifier DEFAULT
+agentcore runtime endpoint list --id <runtimeId> --max-results 20
 ```
 
 ---

src/components/RouterScreen.test.tsx

@@ -15,6 +15,8 @@ describe("menu rendering", () => {
     const frame = r.lastFrame()!;
     expect(frame).toContain("harness");
     expect(frame).toContain("manage agentcore harnesses");
+    expect(frame).toContain("runtime");
+    expect(frame).toContain("inspect AgentCore Runtimes");
     expect(frame).toContain("config");
     expect(frame).toContain("read/write global config values");
     r.unmount();
@@ -86,7 +88,7 @@ describe("navigation", () => {
     await waitForText(r.lastFrame, "❯ harness");
 
     await r.press("down");
-    await waitForText(r.lastFrame, "❯ config");
+    await waitForText(r.lastFrame, "❯ runtime");
     r.unmount();
   });
 

src/core/index.tsx

@@ -2,6 +2,7 @@ import { BedrockAgentCoreControlClient } from "@aws-sdk/client-bedrock-agentcore
 import { BedrockAgentCoreClient } from "@aws-sdk/client-bedrock-agentcore";
 import { IAMClient } from "@aws-sdk/client-iam";
 import { HarnessClient } from "./harness";
+import { RuntimeClient } from "./runtime";
 import type {
   AwsClients,
   ClientConfig,
@@ -29,6 +30,7 @@ export class CoreClient implements AwsClients {
 
   // Feature-scoped sub-clients. Access as e.g. `coreClient.harness.getHarness(...)`.
   readonly harness: HarnessClient = new HarnessClient(this);
+  readonly runtime: RuntimeClient = new RuntimeClient(this);
 
   constructor(
     private readonly createControlClient: CreateControlClient,

src/core/runtime.tsx

@@ -0,0 +1,91 @@
+import {
+  GetAgentRuntimeCommand,
+  GetAgentRuntimeEndpointCommand,
+  ListAgentRuntimeEndpointsCommand,
+  ListAgentRuntimesCommand,
+  ListAgentRuntimeVersionsCommand,
+  type GetAgentRuntimeEndpointResponse,
+  type GetAgentRuntimeResponse,
+  type ListAgentRuntimeEndpointsResponse,
+  type ListAgentRuntimesResponse,
+  type ListAgentRuntimeVersionsResponse,
+} from "@aws-sdk/client-bedrock-agentcore-control";
+import type { CoreRuntimeClient } from "../handlers/runtime/types";
+import type { AwsClients, CoreOptions } from "./types";
+import { toClientConfig } from "./utils";
+
+export class RuntimeClient implements CoreRuntimeClient {
+  constructor(private readonly clients: AwsClients) {}
+
+  async getRuntime(id: string, options: CoreOptions): Promise<GetAgentRuntimeResponse> {
+    return this.clients
+      .control(toClientConfig(options))
+      .send(new GetAgentRuntimeCommand({ agentRuntimeId: id }));
+  }
+
+  async getRuntimeVersion(
+    id: string,
+    version: string,
+    options: CoreOptions,
+  ): Promise<GetAgentRuntimeResponse> {
+    return this.clients.control(toClientConfig(options)).send(
+      new GetAgentRuntimeCommand({
+        agentRuntimeId: id,
+        agentRuntimeVersion: version,
+      }),
+    );
+  }
+
+  async getRuntimeEndpoint(
+    id: string,
+    qualifier: string,
+    options: CoreOptions,
+  ): Promise<GetAgentRuntimeEndpointResponse> {
+    return this.clients.control(toClientConfig(options)).send(
+      new GetAgentRuntimeEndpointCommand({
+        agentRuntimeId: id,
+        endpointName: qualifier,
+      }),
+    );
+  }
+
+  async listRuntimes(
+    nextToken: string | undefined,
+    maxResults: number | undefined,
+    options: CoreOptions,
+  ): Promise<ListAgentRuntimesResponse> {
+    return this.clients
+      .control(toClientConfig(options))
+      .send(new ListAgentRuntimesCommand({ nextToken, maxResults }));
+  }
+
+  async listRuntimeVersions(
+    id: string,
+    nextToken: string | undefined,
+    maxResults: number | undefined,
+    options: CoreOptions,
+  ): Promise<ListAgentRuntimeVersionsResponse> {
+    return this.clients.control(toClientConfig(options)).send(
+      new ListAgentRuntimeVersionsCommand({
+        agentRuntimeId: id,
+        nextToken,
+        maxResults,
+      }),
+    );
+  }
+
+  async listRuntimeEndpoints(
+    id: string,
+    nextToken: string | undefined,
+    maxResults: number | undefined,
+    options: CoreOptions,
+  ): Promise<ListAgentRuntimeEndpointsResponse> {
+    return this.clients.control(toClientConfig(options)).send(
+      new ListAgentRuntimeEndpointsCommand({
+        agentRuntimeId: id,
+        nextToken,
+        maxResults,
+      }),
+    );
+  }
+}

src/handlers/index.tsx

@@ -1,5 +1,6 @@
 import { Router } from "../router";
 import { createHarnessHandler } from "./harness/index.tsx";
+import { createRuntimeHandler } from "./runtime/index.tsx";
 import { DebugKey, EndpointKey, JsonKey, RegionKey } from "./keys.tsx";
 import { createConfigHandler } from "./config/";
 import { createProjectHandler } from "./project/index.ts";
@@ -33,6 +34,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
 
   // Install sub handlers
   root.handler(createHarnessHandler(core, io));
+  root.handler(createRuntimeHandler(core, io));
   root.handler(createConfigHandler(io));
   root.handler(createProjectHandler());
 

src/handlers/root.test.tsx

@@ -9,6 +9,11 @@ describe("createRootHandler", () => {
       logger: createSilentLogger(),
     });
     expect(root.name()).toBe("agentcore");
-    expect(root.children().map((c) => c.name())).toEqual(["harness", "config", "project"]);
+    expect(root.children().map((c) => c.name())).toEqual([
+      "harness",
+      "runtime",
+      "config",
+      "project",
+    ]);
   });
 });

src/handlers/runtime/__fixtures__/GetAgentRuntimeCommand.140854af01fd7827.json

@@ -0,0 +1,33 @@
+{
+  "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+  "agentRuntimeName": "agentcore_cli_runtime_read_only_fixture",
+  "agentRuntimeId": "agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+  "agentRuntimeVersion": "2",
+  "createdAt": {
+    "$date": "2026-07-21T15:24:52.318Z"
+  },
+  "lastUpdatedAt": {
+    "$date": "2026-07-21T15:25:21.499Z"
+  },
+  "roleArn": "arn:aws:iam::685197708687:role/tf_acc_test_1997929140646926281",
+  "networkConfiguration": {
+    "networkMode": "PUBLIC"
+  },
+  "status": "READY",
+  "lifecycleConfiguration": {
+    "idleRuntimeSessionTimeout": 900,
+    "maxLifetime": 28800
+  },
+  "description": "Stable shared resource for AgentCore CLI Runtime read-only fixture recording",
+  "workloadIdentityDetails": {
+    "workloadIdentityArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:workload-identity-directory/default/workload-identity/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx"
+  },
+  "agentRuntimeArtifact": {
+    "containerConfiguration": {
+      "containerUri": "public.ecr.aws/y5s8y8h8/harness-us-west-2:latest"
+    }
+  },
+  "metadataConfiguration": {
+    "requireMMDSV2": true
+  }
+}

src/handlers/runtime/__fixtures__/GetAgentRuntimeCommand.97ebe200714d941e.json

@@ -0,0 +1,33 @@
+{
+  "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+  "agentRuntimeName": "agentcore_cli_runtime_read_only_fixture",
+  "agentRuntimeId": "agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+  "agentRuntimeVersion": "1",
+  "createdAt": {
+    "$date": "2026-07-21T15:24:53.572Z"
+  },
+  "lastUpdatedAt": {
+    "$date": "2026-07-21T15:24:53.572Z"
+  },
+  "roleArn": "arn:aws:iam::685197708687:role/tf_acc_test_1997929140646926281",
+  "networkConfiguration": {
+    "networkMode": "PUBLIC"
+  },
+  "status": "READY",
+  "lifecycleConfiguration": {
+    "idleRuntimeSessionTimeout": 900,
+    "maxLifetime": 28800
+  },
+  "description": "Stable shared resource for AgentCore CLI Runtime read-only fixture recording",
+  "workloadIdentityDetails": {
+    "workloadIdentityArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:workload-identity-directory/default/workload-identity/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx"
+  },
+  "agentRuntimeArtifact": {
+    "containerConfiguration": {
+      "containerUri": "public.ecr.aws/y5s8y8h8/harness-us-west-2:latest"
+    }
+  },
+  "metadataConfiguration": {
+    "requireMMDSV2": true
+  }
+}

src/handlers/runtime/__fixtures__/GetAgentRuntimeCommand.9b8f562f35114475.json

@@ -0,0 +1,6 @@
+{
+  "$error": {
+    "name": "ResourceNotFoundException",
+    "message": "Agent with agentId: missing_runtime-0000000000, accountId: 685197708687, and version: null not found!"
+  }
+}

src/handlers/runtime/__fixtures__/GetAgentRuntimeEndpointCommand.1aa8574ea8360d43.json

@@ -0,0 +1,14 @@
+{
+  "agentRuntimeEndpointArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx/runtime-endpoint/DEFAULT",
+  "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+  "status": "READY",
+  "createdAt": {
+    "$date": "2026-07-21T15:24:52.560Z"
+  },
+  "lastUpdatedAt": {
+    "$date": "2026-07-21T15:25:21.499Z"
+  },
+  "name": "DEFAULT",
+  "id": "DEFAULT",
+  "liveVersion": "2"
+}

src/handlers/runtime/__fixtures__/ListAgentRuntimeEndpointsCommand.140854af01fd7827.json

@@ -0,0 +1,33 @@
+{
+  "runtimeEndpoints": [
+    {
+      "name": "runtimeReadOnlyFixture",
+      "agentRuntimeEndpointArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx/runtime-endpoint/runtimeReadOnlyFixture",
+      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "status": "READY",
+      "id": "runtimeReadOnlyFixture",
+      "createdAt": {
+        "$date": "2026-07-21T15:25:40.102Z"
+      },
+      "lastUpdatedAt": {
+        "$date": "2026-07-21T15:25:40.952Z"
+      },
+      "liveVersion": "2",
+      "description": "Stable shared endpoint for AgentCore CLI Runtime read-only fixture recording"
+    },
+    {
+      "name": "DEFAULT",
+      "agentRuntimeEndpointArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx/runtime-endpoint/DEFAULT",
+      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "status": "READY",
+      "id": "DEFAULT",
+      "createdAt": {
+        "$date": "2026-07-21T15:24:52.560Z"
+      },
+      "lastUpdatedAt": {
+        "$date": "2026-07-21T15:25:21.499Z"
+      },
+      "liveVersion": "2"
+    }
+  ]
+}

src/handlers/runtime/__fixtures__/ListAgentRuntimeEndpointsCommand.1d171c98cd60b7c4.json

@@ -0,0 +1,18 @@
+{
+  "runtimeEndpoints": [
+    {
+      "name": "DEFAULT",
+      "agentRuntimeEndpointArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx/runtime-endpoint/DEFAULT",
+      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "status": "READY",
+      "id": "DEFAULT",
+      "createdAt": {
+        "$date": "2026-07-21T15:24:52.560Z"
+      },
+      "lastUpdatedAt": {
+        "$date": "2026-07-21T15:25:21.499Z"
+      },
+      "liveVersion": "2"
+    }
+  ]
+}

src/handlers/runtime/__fixtures__/ListAgentRuntimeEndpointsCommand.52cf5ddfc336d4d2.json

@@ -0,0 +1,20 @@
+{
+  "runtimeEndpoints": [
+    {
+      "name": "runtimeReadOnlyFixture",
+      "agentRuntimeEndpointArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx/runtime-endpoint/runtimeReadOnlyFixture",
+      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "status": "READY",
+      "id": "runtimeReadOnlyFixture",
+      "createdAt": {
+        "$date": "2026-07-21T15:25:40.102Z"
+      },
+      "lastUpdatedAt": {
+        "$date": "2026-07-21T15:25:40.952Z"
+      },
+      "liveVersion": "2",
+      "description": "Stable shared endpoint for AgentCore CLI Runtime read-only fixture recording"
+    }
+  ],
+  "nextToken": "AQICAHiNyEvxZzpFuVHtBl-B3jfZBBM36tDjm8_cCisOa4ihlgHTCX90veyHQpW0JbzdFgJCAAAB7DCCAegGCSqGSIb3DQEHBqCCAdkwggHVAgEAMIIBzgYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAzXdq_zR1bimIWtQ_0CARCAggGfKjn69njYg3vBDeIAyLfH8q9m_O480LF2QMDi6BTVyJ70W0yKBU6bFBR3UvX61r_dQRqviT_A7gP1nndeLPIVoeaoH5E66U9njh8TO9uBRArYUqmdMtoN2zL4z4pPXncZzBtBDrSetRhOk_Az6YyGFPuZRqbn9o054gP5b4AMLENbckixIotwZPbYl7_WHNev0IZYhNaqXIgDjgyI517p0mRrWfRe4Ddv1G-bpox-6zIg5IVw1K38EQjvdk55Ct0ivrWvPpN_xTqETf6E1nkjtgMu3OGm-sKqZtdpVfAI_1cElM6pDi6HJ2bRx5rNFav1gybOp9mFRGRpNGMpUppDQ-SmCalZ7t8wqWCt0nKzn8kAtBqVOIIMSXwUfgvjiE9IsM2g3nPGSXwmOkKwAl3hck9Y5UQsN8tSyyxSEhqXbEJBra0LRKEtj2f4tVnQ6NHrXxgrfU3TfRopLs1PjRXSY-e_XUScXbQ7taQJDuC1r11isln9EZRje0iQ8unWWSnZvFdVcvAqzfWlz9fG3Kz1bj9fCQ0-l4aeY64N6nJijw=="
+}

src/handlers/runtime/__fixtures__/ListAgentRuntimeVersionsCommand.140854af01fd7827.json

@@ -0,0 +1,26 @@
+{
+  "agentRuntimes": [
+    {
+      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "agentRuntimeId": "agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "agentRuntimeVersion": "2",
+      "agentRuntimeName": "agentcore_cli_runtime_read_only_fixture",
+      "description": "Stable shared resource for AgentCore CLI Runtime read-only fixture recording",
+      "lastUpdatedAt": {
+        "$date": "2026-07-21T15:25:21.499Z"
+      },
+      "status": "READY"
+    },
+    {
+      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:685197708687:runtime/agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "agentRuntimeId": "agentcore_cli_runtime_read_only_fixture-wZ7V4Q6vhx",
+      "agentRuntimeVersion": "1",
+      "agentRuntimeName": "agentcore_cli_runtime_read_only_fixture",
+      "description": "Stable shared resource for AgentCore CLI Runtime read-only fixture recording",
+      "lastUpdatedAt": {
+        "$date": "2026-07-21T15:24:53.572Z"
+      },
+      "status": "READY"
+    }
+  ]
+}