onctl

Onctl

onctl is a tool to manage virtual machines in multi-cloud.

Check 🌍 https://onctl.sh for detailed documentation

What onctl brings

• 🌍 Simple intuitive CLI to run VMs in seconds.
• ⛅️ Supports multi cloud providers (aws, azure, gcp, hetzner, ovh, more coming soon...)
• 📦 Hosted microVMs with the boxes provider: no cloud account, no host to run -- onctl login once with a token from boxctl.io, then onctl create -p boxes. Boxes have no public address; onctl ssh (and plain ssh via onctl ssh-proxy) reach them through the service.
• 🤖 onctl claude: run Claude Code on a box instead of your laptop -- your project copied there, Claude in tmux so it keeps going when you detach, several tasks at once (--task), and the work back as git (onctl claude fetch/push).
• 🔥 Run local microVMs with the fc (Firecracker) provider (Linux + KVM, no cloud account needed). No bare-metal Linux box? Create a nested-virtualization-enabled GCP VM (gcp.vm.nestedVirtualization: true) with onctl create -n fc-host -a firecracker/firecracker-host-setup.sh, then SSH in and run ONCTL_CLOUD=fc onctl create -n my-microvm.
• 🍎 Run local sandboxes on a Mac with the ac (Apple container) provider: each one is a lightweight Linux VM on Virtualization.framework (macOS 26+, no cloud account needed). Install the container CLI, run container system start, then ONCTL_CLOUD=ac onctl create -n my-sandbox (any OCI image via --image; sshd is set up on first boot). pause/resume map to container stop/start.
• 🐮 Run local microVMs with the ch (Cloud Hypervisor) provider — same idea as fc (Linux + KVM, no cloud account needed), no pause/resume support yet. Point ch.kernelImage/ch.rootfsImage at a kernel + rootfs image and run ONCTL_CLOUD=ch onctl create -n my-microvm. Also supports Windows guests via --ch-os windows (UEFI boot) — see TESTING-ch-windows.md for base-image prep; unverified against real hardware.
• 🚀 Sets your public key and Gives you SSH access with onctl ssh <vm-name>
• ✨ Cloud-init support. Set your own cloud-init file onctl up -n qwe --cloud-init <cloud.init.file>
• 🤖 Use ready to use templates to configure your vm. Check onctl-templates onctl up -n qwe -a k3s/k3s-server.sh
• 🗂️ Use your custom local or http accessible scripts to configure your vm. onctl ssh qwe -a <my_local_script.sh>
• 📥 Import a server onctl didn't create (e.g. a Hetzner auction/dedicated box) so you can ssh/ls it too: onctl import <name> --ip <ip>

Quick Start

initialize project. this will create a .onctl directory. check configuration file and set as needed.

❯ onctl init
onctl environment initialized

export ONCTL_CLOUD to set Cloud Provider.

❯ export ONCTL_CLOUD=hetzner

Be sure that credentials for that specific cloud provider is already set. If you already use cloud provider CLI. They're already . ex. az, aws, hcloud

❯ echo $HCLOUD_TOKEN

Create VM.

❯ onctl up -n onctl-test
Using: hetzner
Creating SSHKey: onctl-42da32a9...
SSH Key already exists (onctl-42da32a9)
Starting server...
Server IP: 168.119.58.112
Vm started.

Ssh into VM.

❯ onctl ssh onctl-test
Using: hetzner
Welcome to Ubuntu 22.04.3 LTS (GNU/Linux 5.15.0-89-generic x86_64)
.
.
.
root@onctl-test:~# 

Import an existing server

Already have a server onctl didn't create — a Hetzner auction/dedicated box (these live on Hetzner's Robot API, a different product from Hetzner Cloud, so the hetzner provider can never see them), or any other reachable host? Register it so ssh/ls work against it too:

❯ onctl import myauctionbox --ip 1.2.3.4 --user root --key ~/.ssh/auction_key
✔ Imported "myauctionbox" (1.2.3.4)
Use it with: onctl --provider static ssh myauctionbox

❯ onctl --provider static ls
❯ onctl --provider static ssh myauctionbox

Imported hosts only support ssh/ls/destroy — destroy just forgets the host locally, it never touches the real machine, since onctl didn't create it and has no lifecycle API for it.

Installation

macOS and Linux

curl -sLS https://onctl.sh/get.sh | bash
sudo install onctl /usr/local/bin/

Edge build (latest main, Linux and macOS)

To install or update to the edge build, a binary rebuilt from the tip of main on every push (no Windows build):

curl -sLS https://onctl.sh/get-edge.sh | bash
sudo install onctl /usr/local/bin/

Tab completion

The install scripts also set up tab completion for your shell (bash, zsh or fish): subcommands, flags, and the names of your own VMs, so onctl ssh my-b<TAB> finishes the name for you. Open a new terminal after installing to pick it up.

It works by writing a completion script to your shell's per-user completion folder and, for bash and zsh, adding one line to ~/.bashrc or ~/.zshrc that loads it. To skip this, run the installer with ONCTL_NO_COMPLETION=1:

curl -sLS https://onctl.sh/get.sh | ONCTL_NO_COMPLETION=1 bash

To set it up by hand instead:

echo 'source <(onctl completion bash)' >> ~/.bashrc   # bash
echo 'source <(onctl completion zsh)' >> ~/.zshrc     # zsh
onctl completion fish > ~/.config/fish/completions/onctl.fish

VM names are looked up live from your cloud provider, so completing them needs an initialized .onctl directory and working credentials.

Windows

• download windows binary from releases page
• unzip and copy onctl.exe to a location in PATH

Enjoy ✅

❯ onctl
onctl is a tool to manage cross platform resources in cloud

Usage:
  onctl [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  create      Create a VM
  destroy     Destroy VM(s)
  help        Help about any command
  import      Import an existing server so it can be managed with ssh/ls
  init        init onctl environment
  ls          List VMs
  ssh         Spawn an SSH connection to a VM
  version     Print the version number of onctl

Flags:
  -h, --help   help for onctl

Use "onctl [command] --help" for more information about a command.

Contributing

See CONTRIBUTING.md for how to report issues and what a pull request needs.

For development guidelines — especially when using AI coding agents (opencode, Claude, etc.) — see AGENTS.md.

Important: When running multiple AI agents in parallel on this repo, you must use separate git worktrees (or clones) for isolation. See the "Coordinating multiple agents..." section in AGENTS.md.

Star History