Manage runtimes

The runtime command group manages AgentKit runtimes, covering listing, inspection, log retrieval, version history, releasing, updating, and deletion. Sign in with runtime-management permissions first. Runtimes are scoped by provider and region. Replace example names with results from runtime list; save and use runtime IDs in automation. For BytePlus:

agentkit --provider byteplus runtime list --region ap-southeast-1 --project default

On read commands, --json selects JSON output. On runtime update, it takes a JSON request body. These uses are not interchangeable

runtime list

List all runtimes.

Flag / Argument	Description	Default
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`-p, --project <name>`	Project name.	default
`--json`	Output raw JSON.	`false`
`--gateway-mode <mode>`	Filter by `Shared` or `Exclusive`	—
`--gateway-instance-id <id>`	Filter by gateway instance ID	—

agentkit runtime list --project demo

runtime show

Show details of a runtime, optionally a specific version.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`--rev <n>`	Show a specific version instead of the current one.	current
`--json`	Output raw JSON.	`false`

agentkit runtime show my-agent --rev 3

When --json is used for the current runtime and the runtime is bound to a Tool, the output includes toolId.

Deleting a runtime stops its service, making it unavailable to existing callers. Check callers, associated resources, the ID, and region first. --yes skips confirmation

runtime delete

Delete a runtime.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`-y, --yes`	Skip the confirmation prompt.	`false`

agentkit runtime delete my-agent --yes

runtime logs

Show logs for a runtime instance.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`-i, --instance <name>`	Instance name.	auto-resolve
`-n, --limit <n>`	Number of log lines; `0` = all.	server-side
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`--json`	Output raw JSON.	`false`

agentkit runtime logs my-agent --limit 200

runtime attach

Open an interactive terminal inside a running instance of the runtime, the same shell the console’s instance terminal provides. Press Ctrl-] to detach, which leaves the instance running. When the runtime has scaled to zero and has no instance, one is started automatically before attaching; a runtime using custom_jwt authentication cannot be auto-started without a token, so run agentkit invoke run once first.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`-i, --instance <name>`	Instance to attach to; otherwise a ready instance is used, and you are prompted when several exist.	auto-resolve
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect

agentkit runtime attach my-agent

runtime versions

List a runtime’s version history.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`--json`	Output raw JSON.	`false`

agentkit runtime versions my-agent

runtime release and runtime update --auto-release change the live version; resource changes can also affect charges. --no-wait means the request was submitted, not that the new version is ready

runtime release

Release (publish) a runtime version, making it live.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`--rev <n>`	Version number to release.	latest
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`--no-wait`	Return immediately instead of waiting for `Ready`.	`false`

agentkit runtime release my-agent --rev 3

runtime update

Update a runtime’s configuration. This does not release the new version unless --auto-release is passed.

Flag / Argument	Description	Default
`<runtime>`	Runtime id (`r-...`) or name. Required.	—
`--description <text>`	Description.	—
`--artifact-url <url>`	Container image url.	—
`--artifact-type <type>`	Artifact type.	—
`--cpu-milli <n>`	CPU in milli-cores.	—
`--memory-mb <n>`	Memory in MB.	—
`--min-instance <n>`	Minimum instances.	—
`--max-instance <n>`	Maximum instances.	—
`--max-concurrency <n>`	Maximum concurrency per instance.	—
`--model-agent-name <name>`	Model agent name.	—
`--knowledge-id <id>`	Associated knowledge base id.	—
`--memory-id <id>`	Associated memory collection id.	—
`--tool-id <id>`	Associated tool id.	—
`--mcp-toolset-id <id>`	Associated MCP toolset id.	—
`--apmplus`	Enable APMPlus monitoring.	—
`--no-apmplus`	Disable APMPlus monitoring.	—
`--envs-json <json>`	Env vars as a JSON array, e.g. `'[{"Key":"K","Value":"V"}]'`.	—
`--tags-json <json>`	Tags as a JSON array.	—
`--json <jsonString>`	Advanced: JSON object merged into the request body.	—
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`--auto-release`	Release the new version immediately after updating.	`false`
`--no-wait`	Return immediately instead of waiting for the runtime to settle.	`false`

agentkit runtime update my-agent --cpu-milli 1000 --memory-mb 2048 --auto-release

Gateway details and update restrictions

runtime list displays gateway information, and runtime show includes gateway mode, instance ID, and name. Filter runtimes by their gateway

agentkit runtime list --gateway-mode Exclusive --gateway-instance-id gateway-example --json

Gateway mode, instance, and network configuration are creation-time settings. runtime update --json rejects changes to these fields. Create a runtime under a new name and migrate callers when a different gateway is required

Check publication results

Use runtime versions to confirm the revision, then runtime show to inspect current state. For an instance that is not ready, inspect startup failures with runtime logs. Logs may contain user requests and business data; handle them according to project requirements

agentkit runtime versions my-agent
agentkit runtime show my-agent
agentkit runtime logs my-agent --limit 200

Commands in runtime attach act on the live instance. Changes are not written back to the local project or image. Rebuild and publish project changes when they must persist

Getting Started

AI-Friendly

Command reference

runtime list

runtime show

runtime delete

runtime logs

runtime attach

runtime versions

runtime release

runtime update

Gateway details and update restrictions

Check publication results