Reconfigure a Virtual Machine
reconfigure_virtual_machineChange an existing Cycle virtual machine: its config (hostname, public network mode, ports, egress, CPU, RAM), its guest root password, its assigned SSH keys, or its metadata (name, identifier, annotations, lock, deprecate). Volumes are NOT handled here — VM volume changes exist on Cycle but have no MCP tool yet; surface that gap rather than improvising. The boot image is fixed at create; there is no VM equivalent of a container reimage. The container equivalent is reconfigure_container.
Each group reaches Cycle through a different mechanism and differs in disruption; every change in the preview diff is tagged with an 'impact':
'restart' — config. Cycle's reconfigure REPLACES the VM's entire config, so this tool fetches the current config, applies only the fields you pass, and submits the whole result; everything you don't pass keeps its value (including deployment constraints, startup/shutdown policies, telemetry, and runtime attachments). Applying RESTARTS the VM — a hard interruption of a running guest OS.
'root-password' — the guest's root password, changed by a Cycle job inside the VM. Neither the preview nor the result echoes it; whoever sets it must record it themselves, since Cycle only makes a VM's root password readable for ~10 minutes after creation.
'none' — metadata and SSH key assignment. Applies immediately: no job, no restart. Cycle stores one flat list of assigned keys; add_ssh_keys/remove_ssh_keys read it, apply your changes, and write it back. Keys are written into the guest at provision time, so a running guest may not honor an added key until it restarts, and removing a key does NOT reliably revoke access for a running guest — to be certain, restart the VM (cycle_control_virtual_machine) and verify from inside the guest.
Always call with preview:true first — it fetches the current state and returns a field-by-field from/to diff with each change's impact, making NO changes. The diff is computed by this tool, not validated by Cycle; use it to confirm the change matches the user's intent. Get explicit confirmation, then call again without preview.
Changes from several groups are applied in order — metadata and SSH keys, then config, then root password — and each step is reported in 'steps'. The run stops at the first failed step, so a partial result is possible; read 'steps' rather than assuming all-or-nothing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ram | No | New RAM limit, e.g. '4G'. At least 512M, less than 65G. | |
| lock | No | true blocks delete_virtual_machine until unlocked; false lifts the lock. | |
| name | No | New display name. | |
| cores | No | New core count (1-32), placed by Cycle. Mutually exclusive with cpu_pin; clears any pinning. | |
| ports | No | Complete replacement port list, e.g. ['443:443'] — pass every port wanted. | |
| public | No | New public network access mode. | |
| context | No | Why are you calling this tool? Briefly describe the user's goal. | |
| cpu_pin | No | Pin to specific host cores, e.g. '0-3' ('x' = the host's max core). Mutually exclusive with cores; clears the core count. | |
| preview | No | Return the from/to diff with each change's impact and make NO changes. Always run this first. | |
| hostname | No | New private-network hostname. | |
| deprecate | No | Mark the VM deprecated (true) or undo it (false). | |
| identifier | No | New identifier slug. | |
| annotations | No | Replacement annotation map (user metadata); replaces every existing annotation. | |
| environment | Yes | Environment the VM lives in. | |
| add_ssh_keys | No | Existing environment-scoped SSH keys to assign, by name or 24-char ID. | |
| allocate_ram | No | Preallocate the RAM limit rather than letting the guest grow into it. | |
| wait_seconds | No | Max seconds to wait, across every step this call performs. 0 returns as soon as the jobs are accepted. | |
| root_password | No | New guest root password, at least 10 characters. Confirm with the user and have them record it before applying. | |
| allocate_cores | No | Reserve the cores exclusively so no other VM can use them. | |
| conversation_id | No | Conversation tracking id. Omit on your first tool call; every result then includes a conversation_id line — pass that exact value on all later calls in this conversation. | |
| remove_ssh_keys | No | Assigned SSH keys to unassign, by name or 24-char ID. | |
| virtual_machine | Yes | VM to reconfigure. | |
| egress_via_gateway | No | Route outbound traffic through the Cycle gateway instead of the host. |