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 -- a hosted box, or your own VM on any provider (onctl -p hetzner claude; on a Mac, onctl -p ac claude runs it in an Apple container from the prebuilt claude-agent image) -- a fresh box per run with your project cloned (or copied) there, its work fetched back as box/* and the box deleted when Claude exits (--keep for a long-lived project box; --repo owner/name clones a GitHub repository with no local copy), 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 policy-enforced sandboxes on an NVIDIA OpenShell gateway with the openshell provider: outbound connections are denied by default and credentials stay out of the sandbox. Set up a gateway on any VM with onctl create --image ubuntu-24.04 -a openshell/openshell.sh, register it with openshell gateway add (the template prints how), then onctl create -p openshell -n my-sandbox. Sandboxes are unprivileged, so their software comes from --image, not -a.
• 🐮 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:~# 

Or browse and manage your VMs in a k9s-style terminal UI: s opens a shell, a runs Claude Code on the VM (onctl claude), c creates, p/r pause and resume, ctrl-d destroys, :images and :sizes show what the provider offers, :repos lists your GitHub repositories and enter starts Claude on a box with one cloned (onctl claude --repo), :provider switches clouds, ? lists every key.

❯ onctl tui

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 -fsSL https://onctl.sh/get.sh | bash

The installer downloads the release for your OS and architecture, verifies it against the release checksums, installs onctl to ~/.local/bin (override with ONCTL_INSTALL_DIR), and adds that directory to your PATH in ~/.bashrc, ~/.zshrc or fish's config if it isn't there already. No sudo. Open a new terminal afterwards. To install a specific version, set ONCTL_VERSION=v0.1.34. Windows users can grab onctl-windows-amd64.zip from the releases page.

Edge build (latest main, Linux, macOS and Windows)

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

curl -fsSL https://onctl.sh/get-edge.sh | bash

On Windows, download onctl-windows-amd64.zip from the edge release.

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 -fsSL 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:
  action        Execute a custom action from GitHub
  claude        Run Claude Code on a box, with this project on it
  completion    Generate the autocompletion script for the specified shell
  create        Create a VM
  deploy        Deploy a Docker image to a remote VM
  destroy       Destroy VM(s)
  env           Manage environments
  help          Help about any command
  images        List available OS images for the current cloud provider
  import        Import an existing server so it can be managed with ssh/ls
  init          init onctl environment
  login         Log in to hosted boxes (-p boxes) with a personal token
  logout        Forget the saved boxes token
  ls            List VMs
  pause         Snapshot and delete a VM to stop compute cost (keeps its IP)
  port-forward  Forward local ports to ports on a VM, over ssh
  restart       Cold-boot a VM again from its own disk, optionally on a new kernel (fc)
  resume        Recreate a paused VM from its snapshot
  sizes         List the VM sizes the current provider offers (what --type takes)
  ssh           Spawn an SSH connection to a VM
  ssh-proxy     Relay stdin/stdout to a VM's port through the provider (for ssh's ProxyCommand)
  templates     Manage onctl templates
  tui           Browse and manage your VMs in a k9s-style terminal UI
  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