Runta

View saved version →

---
name: runta-runtimes
description: Manage the lifecycle of Runta runtimes (isolated microVMs) - create, list, inspect, boot, shut down, pause, resume, resize, and delete them. Use when the user asks about their Runta runtimes, sandboxes, or VMs, or wants to change their state.
---

# Runta runtimes

Prefer the Runta MCP tools when they are available. Otherwise, manage runtimes
with the `runta` CLI. If `runta` is missing or a command reports
`MISSING_TOKEN`, `AUTH`, or `UNAUTHENTICATED`, follow the `runta-setup` skill
first.

## MCP tools

When the `runta` MCP server is connected, use these tools instead of the CLI:

| Task | Tool | Arguments |
| --- | --- | --- |
| Show the signed-in account | `whoami` | none |
| List runtimes | `list_runtimes` | optional `status` list, `limit`, `cursor` |
| Inspect one runtime | `get_runtime` | `runtime` (name or id) |
| Create a runtime | `create_runtime` | `name`, optional `image`, `vcpus`, `memory_mib`, `disk_size_gib` |
| Start, stop, pause, resume | `start_runtime`, `stop_runtime`, `pause_runtime`, `resume_runtime` | `runtime` |
| Change memory | `resize_runtime` | `runtime`, `memory_mib` |
| Delete | `delete_runtime` | `runtime` |

The rules below still apply: lifecycle tools return as soon as Runta accepts
the request, so call `get_runtime` until `status` reaches the expected state,
and confirm with the user before `stop_runtime`, `resize_runtime`, or
`delete_runtime`. When `list_runtimes` returns `has_more: true`, pass
`next_cursor` as `cursor` to read the next page. If a tool reports that Runta
no longer accepts the connection, ask the user to reconnect the Runta app.

Use the CLI below for anything the MCP tools don't cover, such as disk resize,
published ports, or idle policies.

## Rules

- Always pass `--json` and read the result from the JSON, not from prose.
- A runtime can be addressed by its name or its UUID. When a name is
  ambiguous or unknown, list runtimes first and confirm which one the user
  means.
- On failure the output is `{"error": {"kind", "code", "message",
  "required_action"?}}` and the exit status is nonzero. Report the message.
  When `required_action.type` is `run_command`, that command is the suggested
  next step.
- Lifecycle requests are asynchronous. A command returning means the API
  accepted the request, not that the runtime reached its new state. Confirm
  with `runta inspect NAME --json` before telling the user the change is done.
- Ask the user to confirm before running `rm`, `shutdown`, or `resize`. Name
  the exact runtimes affected. `rm` permanently deletes the runtime's disk and
  memory. `shutdown` stops every process in the runtime.
- Do not run commands inside a runtime, copy files, or change secrets, egress,
  SSH, or checkpoints. Those are outside this skill.

## Runtime states

`status` is one of `creating`, `running`, `paused`, `suspended`, `shutdown`,
`deleting`, `error`, `crashed`, or `unavailable`. `desired_status` is the
state Runta is moving toward. `degraded: true` on a running runtime means it
has not reported a heartbeat for at least 60 seconds.

## List and inspect

```bash
runta ps -a --json            # every runtime: id, name, status, vcpus, memory_mib, image_id
runta ps --json               # only running and suspended runtimes
runta inspect NAME --json     # full runtime object under "runtime"
```

In `inspect` output, read `runtime.status`, `runtime.desired_status`,
`runtime.vcpus`, and `runtime.cur_memory_mib`.

## Create

```bash
runta run --name NAME --wait --json
```

Optional flags:

- `--image ID`: Runtime Image variant. Omit it for the default image.
- `--cpus N` and `--memory MIB`: sizes. Omit them to use the image's
  recommendation.
- `--disk-size-gib GIB`: writable disk size.
- `--publish PORT/http` or `--publish PORT/https`: repeatable ingress rule.
- `--idle-mode suspend-only|suspend-and-wakeup --idle-timeout SECS`: suspend
  the runtime when idle.
- `--timeout-secs SECS`: how long `--wait` polls (default 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: runta-setup
description: Install the Runta CLI and sign in to Runta. Use before any Runta runtime task when the `runta` command is missing, a Runta command reports `MISSING_TOKEN` or `AUTH`, or the user asks to connect, log in to, or switch Runta environments.
---

# Runta setup

If the Runta MCP tools are connected, call `whoami`. When it returns the
user's account, setup is complete and the CLI is not needed. When the client
asks the user to sign in to Runta, let the user finish that browser sign-in;
never ask for a token in the chat.

Without the MCP tools, Runta runtime tasks run through the `runta` CLI.
Confirm it is installed and signed in before doing anything else.

## 1. Check the CLI

```bash
runta --version
```

If the command is not found, install the CLI and check again:

```bash
npm install -g @runta/runta-cli
```

Do not install the CLI any other way unless the user asks.

## 2. Check authentication

```bash
runta ps --json
```

- `{"action": "ps", "runtimes": [...]}` means the CLI is signed in. Stop here.
- `error.code` of `MISSING_TOKEN`, `AUTH`, or `UNAUTHENTICATED` means the CLI
  needs to sign in. Continue to step 3.
- `error.code` of `TRANSPORT` or `INVALID_ENDPOINT`, or an `SDK` error whose
  message starts with `http error`, means the API is unreachable or
  misconfigured. Show the user the message and the current `RUNTA_ENDPOINT`
  value, if set. Do not try to sign in.

## 3. Sign in

Prefer the browser device flow. It never exposes a secret in the conversation.

```bash
runta login --no-wait --json
```

The output has `status: "authorization_pending"`, a `user_code`, and a
`verification_uri_complete`. Give the user the link and the code, and ask them
to approve the request in their browser. Then wait for approval:

```bash
runta login --resume --wait --json
```

Run `runta ps --json` again to confirm sign-in worked.

If the user already has an API key, they can set `RUNTA_TOKEN` in the
environment instead. Never ask the user to paste an API key into the chat, and
never print, log, or store the value of `RUNTA_TOKEN`.

## Environments

The CLI talks to production by default. To target another environment, the
user sets `RUNTA_ENDPOINT` to that API base URL, for example
`http://127.0.0.1:8080` for the local development stack. Only change
`RUNTA_ENDPOINT` when the user asks.