samples/nb.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Intro\n",
    "\n",
    "This notebook provides a quickstart guide to the pylume python library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install pylume"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If locally installed, use this instead:\n",
    "# !poetry install\n",
    "# !poetry build\n",
    "!pip uninstall pylume -y && pip install ./dist/pylume-0.1.0-py3-none-any.whl --force-reinstall"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import asyncio\n",
    "from pylume import (\n",
    "    PyLume, \n",
    "    ImageRef, \n",
    "    VMRunOpts, \n",
    "    SharedDirectory, \n",
    "    VMConfig,\n",
    "    VMUpdateOpts\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get latest IPSW URL from Apple Server\n",
    "\n",
    "This is used to create a new macOS VM by providing the downloaded IPSW file path to the `ipsw` argument in the `create_vm` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async def get_ipsw():\n",
    "    async with PyLume(debug=True) as pylume:\n",
    "        url = await pylume.get_latest_ipsw_url()\n",
    "        print(f\"Latest IPSW URL: {url}\")\n",
    "\n",
    "await get_ipsw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a new VM"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### macOS\n",
    "\n",
    "An IPSW file path is required to create a new macOS VM. To fetch automatically the latest IPSW during the VM creation, use `ipsw=\"latest\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async def create_macos_vm():\n",
    "    async with PyLume() as pylume:\n",
    "        vm_config = VMConfig(\n",
    "            name=\"macos-vm\",\n",
    "            os=\"macOS\",\n",
    "            cpu=4,\n",
    "            memory=\"4GB\",\n",
    "            disk_size=\"40GB\",\n",
    "            display=\"1024x768\",\n",
    "            ipsw=\"latest\"\n",
    "        )\n",
    "        await pylume.create_vm(vm_config)\n",
    "\n",
    "await create_macos_vm()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Linux\n",
    "\n",
    "To create a new Linux VM, use the `os=\"linux\"` argument in the `VMConfig` class. Note that this doesn't set up any Linux distribution, it just creates a VM with a Linux kernel."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async def create_linux_vm():\n",
    "    async with PyLume() as pylume:\n",
    "        vm_config = VMConfig(\n",
    "            name=\"linux-vm\",\n",
    "            os=\"linux\",\n",
    "            cpu=2,\n",
    "            memory=\"4GB\",\n",
    "            disk_size=\"25GB\",\n",
    "            display=\"1024x768\"\n",
    "        )\n",
    "        await pylume.create_vm(vm_config)\n",
    "\n",
    "await create_linux_vm()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Pull an image from ghcr.io/trycua"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cua provides pre-built images for macOS and Linux."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async def pull_macos_image():\n",
    "    async with PyLume() as pylume:\n",
    "        image_ref = ImageRef(\n",
    "            image=\"macos-sequoia-vanilla\",\n",
    "            tag=\"15.2\",\n",
    "            registry=\"ghcr.io\",\n",
    "            organization=\"trycua\"\n",
    "        )\n",
    "        await pylume.pull_image(image_ref, name=\"macos-sequoia-vanilla\")\n",
    "\n",
    "await pull_macos_image()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run\n",
    "\n",
    "Run a VM by providing the `VMRunConfig` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async def run_vm():\n",
    "    async with PyLume() as pylume:\n",
    "        vm_name = \"macos-sequoia-vanilla\"\n",
    "        run_opts = VMRunOpts(\n",
    "            no_display=False,\n",
    "            shared_directories=[\n",
    "                SharedDirectory(\n",
    "                    host_path=\"/Users/<USER>/Shared\",\n",
    "                    read_only=False\n",
    "                )\n",
    "            ]\n",
    "        )\n",
    "        await pylume.run_vm(vm_name, run_opts)\n",
    "\n",
    "await run_vm()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### List existing VMs\n",
    "\n",
    "VMs are stored in the `~/.lume` directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async with PyLume() as pylume:\n",
    "    vms = await pylume.list_vms()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get VM status"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async with PyLume() as pylume:\n",
    "    status = await pylume.get_vm(\"macos-sequoia-vanilla\")\n",
    "    print(status)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update VM Settings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "update_config = VMUpdateOpts(\n",
    "    cpu=8,\n",
    "    memory=\"8GB\"\n",
    ")\n",
    "async with PyLume() as pylume:\n",
    "    await pylume.update_vm(\"macos-sequoia-vanilla\", update_config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Stop a VM"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async with PyLume() as pylume:\n",
    "    await pylume.stop_vm(\"macos-sequoia-vanilla\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delete a VM"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async with PyLume() as pylume:\n",
    "    await pylume.delete_vm(\"linux-vm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Images\n",
    "\n",
    "List the images available locally"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "async with PyLume() as pylume:\n",
    "    await pylume.get_images()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}