> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash lines theme={null}
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 | — |

```bash lines theme={null}
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` |

```bash lines theme={null}
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`.

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

## 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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
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 |

```bash lines theme={null}
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` |

```bash lines theme={null}
agentkit runtime versions my-agent
```

<Warning>
  `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
</Warning>

## 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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
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

```bash lines theme={null}
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

```bash lines theme={null}
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