---
title: "Execute a command inside a VM using WebSocket protocol"
method: GET
path: "/vms/{name}/exec"
tags: ["vms"]
---

# Execute a command inside a VM using WebSocket protocol

`GET /vms/{name}/exec`

## Query parameters

- `command` string
- `session` string
- `cmux_session_id` string
- `interactive` boolean
- `stdin` boolean
- `tty` boolean
- `rows` integer
- `cols` integer
- `env` object
- `workdir` string
- `wait` integer

## Headers

- `Connection` string, required
- `Upgrade` string, required

## Other responses

- `101` — The connection has been upgraded to WebSocket. Messages exchanged after upgrade: * Orchard Client → Orchard Controller: `ExecClientFrame` * Orchard Controller → Orchard Client : `ExecControllerFrame`
- `400` — Invalid parameters were supplied
- `404` — VM resource with the given name or reconnectable exec session doesn't exist
- `409` — Reconnectable exec session already exists with different options
- `503` — Controller failed to establish a connection with the VM

## Changes

- **2026-05-05** `4dc9d4b10d02` — 1 breaking, 8 info
  - added `#/components/schemas/ExecClientFrameResize` to the `oneOf[#/components/schemas/ExecClientFrame]/` response property `oneOf` list for the response status `101`
  - added the new optional `query` request parameter `cols`
  - added the new optional `query` request parameter `env`
  - added the new optional `query` request parameter `interactive`
  - …5 more
- **2026-05-04** `a4f7b823bb7c` — 2 breaking, 10 info
  - added `#/components/schemas/ExecClientFrameHistory, #/components/schemas/ExecClientFrameAck, #/components/schemas/ExecClientFrameDetach, #/components/schemas/ExecClientFrameClose` to the `oneOf[#/components/schemas/ExecClientFrame]/` response property `oneOf` list for the response status `101`
  - added `#/components/schemas/ExecControllerFrameNoMoreHistory` to the `oneOf[#/components/schemas/ExecControllerFrame]/` response property `oneOf` list for the response status `101`
  - added the new optional `query` request parameter `cmux_session_id`
  - added the new optional `query` request parameter `session`
  - …8 more
- **2026-02-12** `06df38f97806` — 1 info
  - endpoint added
- **2023-01-26** `4b9547159dde` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/openai/apis/orchard/changes/vms/:name/exec/get.md)

---

[API](https://skmtc.dev/openai/apis/orchard.md) · [All operations](https://skmtc.dev/openai/apis/orchard/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openai/orchard/revisions/d599e69bf6be/schema)