### Run Linux VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Starts the 'ubuntu' virtual machine after installation.

```bash
tart run ubuntu
```

--------------------------------

### Install Golang with Homebrew

Source: https://github.com/openai/tart/blob/main/benchmark/README.md

Installs the Golang development environment using Homebrew. Ensure Golang is installed before running benchmarks.

```shell
brew install go
```

--------------------------------

### Install and Run Orchard in Development Mode

Source: https://github.com/openai/tart/blob/main/docs/orchard/quick-start.md

Install Orchard using Homebrew and start it in local development mode. This runs both the Controller and Worker in a single process for testing.

```shell
brew install cirruslabs/cli/orchard
orchard dev
```

--------------------------------

### Basic Cirrus CLI Task Configuration

Source: https://github.com/openai/tart/blob/main/docs/integrations/cirrus-cli.md

Example `.cirrus.yml` to start a Tart VM, copy the working directory, and run scripts inside the VM. This is useful for setting up a consistent environment for task execution.

```yaml
task:
  name: hello
  macos_instance:
    # can be a remote or a local virtual machine
    image: ghcr.io/cirruslabs/macos-tahoe-base:latest
  hello_script:
    - echo "Hello from within a Tart VM!"
    - echo "Here is my CPU info:"
    - sysctl -n machdep.cpu.brand_string
    - sleep 15
```

--------------------------------

### Install Ubuntu in VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Installs Ubuntu into the 'ubuntu' VM using the 'focal-desktop-arm64.iso' disk image.

```bash
tart run --disk focal-desktop-arm64.iso ubuntu
```

--------------------------------

### Enable and Start Orchard Controller Service on Debian

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Enables the Orchard Controller service to start on boot and then starts the service immediately.

```shell
sudo systemctl enable orchard-controller
sudo systemctl start orchard-controller
```

--------------------------------

### Run macOS VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Starts the 'tahoe-vanilla' virtual machine. Manual macOS installation is required after initial boot.

```bash
tart run tahoe-vanilla
```

--------------------------------

### Install Orchard CLI

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2023-04-25-orchard-ga.md

Install the Orchard CLI using Homebrew for local development.

```bash
brew install cirruslabs/cli/orchard
```

--------------------------------

### Enable and Start Orchard Controller Service on RPM-based Systems

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Enables the Orchard Controller service to start on boot and then starts the service immediately using systemctl.

```shell
systemctl enable orchard-controller
systemctl start orchard-controller
```

--------------------------------

### Install and Run Cirrus CLI

Source: https://github.com/openai/tart/blob/main/docs/integrations/cirrus-cli.md

Commands to install Cirrus CLI using Homebrew and then run a `.cirrus.yml` configuration file. Ensure you have Homebrew installed before running the installation command.

```bash
brew install cirruslabs/cli/cirrus
cirrus run
```

--------------------------------

### Create a VM with specific labels

Source: https://github.com/openai/tart/blob/main/docs/orchard/using-orchard-cli.md

Create a virtual machine and schedule it on workers that match the specified labels. For example, schedule on Mac Studio workers.

```shell
orchard create vm --labels model=macstudio <NAME>
```

--------------------------------

### Create a VM with specific resource requirements

Source: https://github.com/openai/tart/blob/main/docs/orchard/using-orchard-cli.md

Create a virtual machine and schedule it on workers that have sufficient specified resources, such as bandwidth. This example schedules a VM requiring 7500 Mbps bandwidth.

```shell
orchard create vm --resources bandwidth-mbps=7500 <NAME>
```

--------------------------------

### Install APT Transport and Certificates on Debian

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Installs necessary packages for APT to handle HTTPS repositories and X.509 certificates. Run this before adding new repositories.

```shell
sudo apt-get update && sudo apt-get -y install apt-transport-https ca-certificates
```

--------------------------------

### time(1) Output Example

Source: https://github.com/openai/tart/blob/main/PROFILING.md

This is an example of the detailed output provided by `time(1)` after a Tart process completes, showing metrics like real time, user time, system time, and maximum resident set size.

```text
      172.17 real        10.29 user         8.36 sys
           353796096  maximum resident set size
                   0  average shared memory size
                   0  average unshared data size
                   0  average unshared stack size
               23838  page reclaims
                  35  page faults
                   0  swaps
                   0  block input operations
                   0  block output operations
                   8  messages sent
                   8  messages received
                   0  signals received
                 146  voluntary context switches
              222950  involuntary context switches
         39683070975  instructions retired
         27562035252  cycles elapsed
           170920448  peak memory footprint
```

--------------------------------

### Install GitLab Tart Executor via Homebrew

Source: https://github.com/openai/tart/blob/main/docs/integrations/gitlab-runner.md

Install the `gitlab-tart-executor` binary using Homebrew. This is the initial step for setting up the Tart Executor for GitLab Runner.

```bash
brew install cirruslabs/cli/gitlab-tart-executor
```

--------------------------------

### Install Orchard Controller on Debian

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Updates the package index and installs the Orchard Controller package from the configured repository.

```shell
sudo apt-get update && sudo apt-get -y install orchard-controller
```

--------------------------------

### Manual Tart Installation and VM Execution

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Manually install the Tart binary by downloading the release archive, extracting it, and then cloning and running a macOS VM. Ensure you use the specific binary path for elevated privileges.

```bash
curl -LO https://github.com/openai/tart/releases/latest/download/tart.tar.gz
tar -xzvf tart.tar.gz
./tart.app/Contents/MacOS/tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base
./tart.app/Contents/MacOS/tart run tahoe-base
```

--------------------------------

### SSH Connection Example

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

An example of how to SSH into a VM managed by Orchard Controller when the SSH server functionality is enabled. This command uses the service account name and controller address to establish the connection.

```shell
ssh -J <service account name>@orchard-controller.example.com <VM name>
```

--------------------------------

### Install and Run Tart VM

Source: https://github.com/openai/tart/blob/main/README.md

Installs Tart using Homebrew, clones a macOS VM image from a registry, and runs it. Requires macOS 13.0 (Ventura) or later.

```bash
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base
tart run tahoe-base
```

--------------------------------

### Install Orchard Controller on RPM-based Systems

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Installs the Orchard Controller package using yum or dnf from the configured Cirrus Labs repository.

```shell
sudo yum -y install orchard-controller
```

--------------------------------

### Verify Orchard Installation Path

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-workers.md

Checks the installation path of the Orchard CLI. This path is used in launchd job definitions.

```shell
which orchard
```

--------------------------------

### Install SSH Server in Linux VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Installs the OpenSSH server and configures the firewall to allow SSH connections within the Linux VM.

```bash
sudo apt update
sudo apt install -y openssh-server
sudo ufw allow ssh
```

--------------------------------

### Cirrus CLI Task Configuration with Artifacts

Source: https://github.com/openai/tart/blob/main/docs/integrations/cirrus-cli.md

Example `.cirrus.yml` to build a binary within a Tart VM and expose it as an artifact. This is useful for CI/CD pipelines where build outputs need to be collected.

```yaml
task:
  name: Build
  macos_instance:
    image: ghcr.io/cirruslabs/macos-tahoe-xcode:latest
  build_script: swift build --product tart
  binary_artifacts:
    path: .build/debug/tart
```

--------------------------------

### Install Samba on Linux VMs

Source: https://github.com/openai/tart/blob/main/docs/faq.md

Install Samba on Linux VMs to ensure the host's ARP table is populated, which is necessary for the `tart ip --resolver=arp` command to function correctly.

```shell
sudo apt-get install samba
```

--------------------------------

### Install Ansible Galaxy Dependencies

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-workers.md

Installs the necessary dependencies for the Ansible playbook from requirements.yml.

```shell
ansible-galaxy install -r requirements.yml
```

--------------------------------

### Run Orchard Controller with a Custom Bootstrap Admin Token

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Use this command to run the Orchard Controller and set a secure, random token for the bootstrap admin service account. This is useful for initial setup or when resetting credentials.

```bash
ORCHARD_BOOTSTRAP_ADMIN_TOKEN=$(openssl rand -hex 32) orchard controller run
```

--------------------------------

### Use Tart Images in GitLab CI Configuration

Source: https://github.com/openai/tart/blob/main/docs/integrations/gitlab-runner.md

Example of a `.gitlab-ci.yml` file demonstrating how to specify a Tart Image for a job. The Tart Executor will pull the specified image to create ephemeral VMs for job execution.

```yaml
# You can use any remote Tart Image.
# Tart Executor will pull it from the registry and use it for creating ephemeral VMs.
image: ghcr.io/cirruslabs/macos-tahoe-base:latest

test:
  tags:
    - tart-installed # in case you tagged runners with Tart Executor installed
  script:
    - uname -a
```

--------------------------------

### Fetch GitHub Releases and Calculate Downloads

Source: https://github.com/openai/tart/blob/main/docs/theme/overrides/home.html

This JavaScript snippet fetches release data from the GitHub API for the OpenAI Tart repository and calculates the total download count for binary assets. It then updates a DOM element with the rounded installation count, including a baseline for versions prior to 1.0.0.

```javascript
fetch("https://api.github.com/repos/openai/tart/releases?per_page=100")
  .then((response) => response.json())
  .then((releases) => {
    let allDownloads = 0;
    for (let release of releases) {
      for (let asset of release.assets) {
        if (asset && asset.content_type === "application/octet-stream") {
          allDownloads += asset.download_count || 0;
        }
      }
    }
    let counterElement = document.getElementById('installation-counter');
    if (counterElement) {
      // Live installation count is available starting version 1.0.0
      // Prior Tart was installed a little over 14,000 times, let's count them too
      let installationPriorV1 = 14;
      counterElement.textContent = (installationPriorV1 + Math.round(allDownloads / 1000)) + ",000";
    }
  })
```

--------------------------------

### Load launchd Worker Job

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-workers.md

Loads and starts the Orchard Worker job defined in the launchd plist file.

```shell
launchctl load -w /Library/LaunchDaemons/org.cirruslabs.orchard.worker.plist
```

--------------------------------

### Add Cirrus Labs Repository on Debian

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Adds the Cirrus Labs APT repository to your system's sources list. This allows you to install packages from Cirrus Labs.

```shell
echo "deb [trusted=yes] https://apt.fury.io/cirruslabs/ /" | sudo tee /etc/apt/sources.list.d/cirruslabs.list
```

--------------------------------

### Create, Log, and Delete VM in Python

Source: https://github.com/openai/tart/blob/main/docs/orchard/integration-guide.md

This Python snippet shows how to create a VM with a startup script, retrieve its logs, and then delete it. Ensure you handle potential errors during these operations.

```python
import time
import uuid

import requests
from requests.auth import HTTPBasicAuth


def main():
  vm_name = str(uuid.uuid4())

  basic_auth = HTTPBasicAuth("service account name", "service account token")

  # Create VM
  response = requests.post("http://127.0.0.1:6120/v1/vms", auth=basic_auth, json={
    "name": vm_name,
    "image": "ghcr.io/cirruslabs/macos-tahoe-base:latest",
    "cpu": 4,
    "memory": 4096,
    "startup_script": {
      "script_content": "date",
    }
  })
  response.raise_for_status()

  # Retrieve VM's logs
  while True:
    response = requests.get(f"http://127.0.0.1:6120/v1/vms/{vm_name}/events", auth=basic_auth)
    response.raise_for_status()

    result = response.json()

    if isinstance(result, list) and len(result) != 0:
      print(result[0]["payload"])
      break

    time.sleep(1)

  # Delete VM
  response = requests.delete(f"http://127.0.0.1:6120/v1/vms/{vm_name}", auth=basic_auth)
  response.raise_for_status()


if __name__ == '__main__':
  main()
```

--------------------------------

### Create, Log, and Delete VM in Golang

Source: https://github.com/openai/tart/blob/main/docs/orchard/integration-guide.md

This Golang snippet demonstrates creating a VM, fetching its logs, and then deleting it. The Orchard Golang API client handles context automatically.

```go
package main

import (
  "context"
  "fmt"
  "github.com/cirruslabs/orchard/pkg/client"
  v1 "github.com/cirruslabs/orchard/pkg/resource/v1"
  "github.com/google/uuid"
  "log"
  "time"
)

func main() {
  vmName := uuid.New().String()

  client, err := client.New()
  if err != nil {
    log.Fatalf("failed to initialize Orchard API client: %v", err)
  }

  # Create VM
  err = client.VMs().Create(context.Background(), &v1.VM{
    Meta: v1.Meta{
      Name: vmName,
    },
    Image:  "ghcr.io/cirruslabs/macos-tahoe-base:latest",
    CPU:    4,
    Memory: 4096,
    StartupScript: &v1.VMScript{
      ScriptContent: "date",
    },
  })
  if err != nil {
    log.Fatalf("failed to create VM: %v")
  }

  # Retrieve VM's logs
  for {
    vmLogs, err := client.VMs().Logs(context.Background(), vmName)
    if err != nil {
      log.Fatalf("failed to retrieve VM logs")
    }

    if len(vmLogs) != 0 {
      fmt.Println(vmLogs[0])
      break
    }

    time.Sleep(time.Second)
  }

  # Delete VM
  if err := client.VMs().Delete(context.Background(), vmName); err != nil {
    log.Fatalf("failed to delete VM: %v", err)
  }
}
```

--------------------------------

### Create a Virtual Machine with Orchard

Source: https://github.com/openai/tart/blob/main/docs/orchard/quick-start.md

Create a new virtual machine using a specified base image. The VM will be named 'tahoe-base'.

```shell
orchard create vm --image ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base
```

--------------------------------

### Resize Linux VM Disk and Run

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Clone a Linux VM image, resize its disk to a larger size, and then run it. This is useful for Linux images that come with a minimal disk size.

```bash
tart clone ghcr.io/cirruslabs/ubuntu:latest ubuntu
tart set ubuntu --disk-size 50
tart run ubuntu
```

--------------------------------

### Create Google Compute Engine Instance with Orchard Controller Container

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Creates a Google Compute Engine instance named 'orchard-controller' with the Orchard Controller running in a container. It configures the machine type, zone, image, network tags, static IP address, container image, environment variables, and host path mounts.

```bash
gcloud compute instances create-with-container orchard-controller \
  --machine-type=e2-micro \
  --zone=us-central1-a \
  --image-family cos-stable \
  --image-project cos-cloud \
  --tags=https-server \
  --address=$ORCHARD_IP \
  --container-image=ghcr.io/cirruslabs/orchard:latest \
  --container-env=PORT=443 \
  --container-env=ORCHARD_BOOTSTRAP_ADMIN_TOKEN=$ORCHARD_BOOTSTRAP_ADMIN_TOKEN \
  --container-mount-host-path=host-path=/home/orchard-data,mode=rw,mount-path=/data
```

--------------------------------

### Create Linux VM (Ubuntu)

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Creates a bare Linux virtual machine, specifically for Ubuntu. This command requires macOS 13.0 (Ventura) or newer.

```bash
tart create --linux ubuntu
```

--------------------------------

### Run FIO Benchmark

Source: https://github.com/openai/tart/blob/main/benchmark/README.md

Executes a Flexible I/O tester benchmark comparing host and guest performance. Requires a base macOS image and may involve a preparation step for the guest environment.

```shell
go run cmd/main.go fio --image ghcr.io/cirruslabs/macos-tahoe-base:latest --prepare 'sudo purge && sync'
```

--------------------------------

### Get Router IP Address

Source: https://github.com/openai/tart/blob/main/docs/faq.md

Retrieves the IP address of the router, which is used to access services running on the host machine from within a virtual machine using the default NAT network.

```shell
netstat -nr | awk '/default/{print $2; exit}'
```

--------------------------------

### Mount Multiple Host Directories to VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Runs a VM and mounts two directories, '~/project1/www' as 'www1' and '~/project2/www' as 'www2'. Requires macOS 13.0 (Ventura) or newer.

```bash
tart run --dir=www1:~/project1/www --dir=www2:~/project2/www
```

--------------------------------

### Change Default NAT Subnet Address

Source: https://github.com/openai/tart/blob/main/docs/faq.md

Modify the default NAT subnet address for vmnet framework. Note that the vmnet framework treats network-like values (e.g., 192.168.77.0) as starting addresses and may refuse them.

```shell
sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.vmnet.plist Shared_Net_Address -string 192.168.77.1
```

--------------------------------

### Basic Buildkite Tart Plugin Configuration

Source: https://github.com/openai/tart/blob/main/docs/integrations/buildkite.md

This is a basic configuration for the Tart Buildkite Plugin. It specifies the command to run and the base macOS image to use for the ephemeral VM.

```yaml
steps:
- command: uname -a
  plugins:
  - cirruslabs/tart#main:
    image: ghcr.io/cirruslabs/macos-tahoe-base:latest
```

--------------------------------

### Run Orchard in Development Mode

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2023-04-25-orchard-ga.md

Launch a local development cluster with a single worker using the Orchard CLI.

```bash
orchard dev
```

--------------------------------

### Upgrade Tart and Pull Sonoma Image

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2023-09-20-tart-2.0.0.md

Upgrade your Tart installation to the latest version and pull the macOS Sonoma base image. This command ensures you have the newest features, including the improved image format for faster and resumable pulls.

```bash
brew upgrade cirruslabs/cli/tart
tart pull ghcr.io/cirruslabs/macos-sonoma-base:latest
```

--------------------------------

### Run Tart Build Script

Source: https://github.com/openai/tart/blob/main/CONTRIBUTING.md

Execute the signed build script for Tart. This command is used to initiate the build process.

```bash
./scripts/run-signed.sh list
```

--------------------------------

### Push Local Image to Registry

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Push a local VM image to a remote registry with multiple tags. Ensure you are logged in to the registry first.

```bash
tart push my-local-vm-name acme.io/remoteorg/name:latest acme.io/remoteorg/name:v1.0.0
```

--------------------------------

### Mount Host Directory to VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Runs a VM named 'vm' and mounts the host directory '~/src/project' to the VM as 'project'. Requires macOS 13.0 (Ventura) or newer.

```bash
tart run --dir=project:~/src/project vm
```

--------------------------------

### Create a new Orchard Controller context

Source: https://github.com/openai/tart/blob/main/docs/orchard/using-orchard-cli.md

Configure a new context to communicate with an Orchard Controller. Assumes default port 6120.

```shell
orchard context create orchard-controller.example.com
```

--------------------------------

### Create macOS VM from IPSW

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Creates a new macOS virtual machine using the latest available IPSW file. The VM is named 'tahoe-vanilla'.

```bash
tart create --from-ipsw=latest tahoe-vanilla
```

--------------------------------

### Connect to a Virtual Machine via VNC

Source: https://github.com/openai/tart/blob/main/docs/orchard/quick-start.md

Open a VNC connection (Screen Sharing) to a remote virtual machine. Defaults to 'admin' username and 'admin' password.

```shell
orchard vnc vm tahoe-base
```

--------------------------------

### Configure Cirrus Labs Repository on RPM-based Systems

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Creates a repository configuration file for yum/dnf to access the Cirrus Labs repository. GPG checking is disabled for simplicity.

```ini
[cirruslabs]
name=Cirrus Labs Repo
baseurl=https://yum.fury.io/cirruslabs/
enabled=1
gpgcheck=0
```

--------------------------------

### Clone Remote Image to Local VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Create a local VM directly from a remote image. If the image is not present locally, it will be pulled automatically.

```bash
tart clone acme.io/remoteorg/name:latest my-local-vm-name
```

--------------------------------

### Xcode Benchmark Comparison Table

Source: https://github.com/openai/tart/blob/main/benchmark/README.md

This table shows the execution time of an Xcode benchmark run locally and with various Tart configurations. It highlights the performance differences based on Tart's root disk options.

```text
Name					Executor					Time 
XcodeBenchmark (d869315)	local					2m19s
XcodeBenchmark (d869315)	Tart					3m59s
XcodeBenchmark (d869315)	Tart (--root-disk-opts="sync=none")		3m48s
XcodeBenchmark (d869315)	Tart (--root-disk-opts="caching=cached")		3m35s
XcodeBenchmark (d869315)	Tart (--root-disk-opts="sync=none,caching=cached")	3m14s
```

--------------------------------

### List Virtual Machines with Orchard

Source: https://github.com/openai/tart/blob/main/docs/orchard/quick-start.md

Display a list of all virtual machines managed by Orchard to check their status.

```shell
orchard list vms
```

--------------------------------

### Configure Auto-mount for Shared Directory in Linux

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Adds an entry to '/etc/fstab' to automatically mount the shared directory at '/mnt/shared' on boot in the Linux guest.

```shell
com.apple.virtio-fs.automount /mnt/shared virtiofs rw,relatime 0 0
```

--------------------------------

### Connect to VM via SSH

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Connect to a running VM using SSH. This command retrieves the VM's IP address and uses it to establish an SSH connection with default credentials.

```bash
ssh admin@$(tart ip tahoe-base)
```

--------------------------------

### Create and Unlock Login Keychain

Source: https://github.com/openai/tart/blob/main/docs/faq.md

Automates the creation and unlocking of the login keychain for headless machines. Note that this creates a keychain with an empty password; consider using a strong password or interactive input for better security.

```shell
security create-keychain -p '' login.keychain
security unlock-keychain -p '' login.keychain
security login-keychain -s login.keychain
```

--------------------------------

### Enable SSH Server for Direct VM Connections

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Run the Orchard Controller with the `--listen-ssh` argument to enable its built-in SSH server. This allows direct SSH connections to VMs within the Orchard Cluster, bypassing the Orchard API for connections.

```bash
orchard controller run --listen-ssh 6122
```

--------------------------------

### Create Orchard Context for Local Client

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Creates a new context named 'production' for the local Orchard client, specifying the service account and token, and the HTTPS endpoint of the Orchard Controller.

```bash
orchard context create --name production \
  --service-account-name bootstrap-admin \
  --service-account-token $ORCHARD_BOOTSTRAP_ADMIN_TOKEN \
  https://$ORCHARD_IP:443
```

--------------------------------

### SSH into a Virtual Machine

Source: https://github.com/openai/tart/blob/main/docs/orchard/quick-start.md

Connect to a virtual machine using SSH. Defaults to 'admin' username and 'admin' password.

```shell
orchard ssh vm tahoe-base
```

--------------------------------

### Create Orchard Context without PKI

Source: https://github.com/openai/tart/blob/main/docs/orchard/architecture-and-security.md

Use this command to create a new Orchard context without relying on PKI. It allows interactive verification of the Controller's certificate fingerprint, establishing a non-PKI association.

```bash
orchard context create --no-pki
```

--------------------------------

### Format Code with SwiftFormat

Source: https://github.com/openai/tart/blob/main/CONTRIBUTING.md

Automatically format Swift code using SwiftFormat plugin. Ensure code adheres to project style guidelines.

```bash
swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore .
```

--------------------------------

### Disk I/O Benchmark Table

Source: https://github.com/openai/tart/blob/main/benchmark/README.md

This table displays disk I/O performance metrics for various operations when using Tart compared to local execution. It includes bandwidth, IOPS, and latency for different configurations.

```text
Name                                    	Executor                                          	B/W (read) 	B/W (write) 	I/O (read) 	I/O (write) 	Latency (read)            	Latency (write)           	Latency (sync)         
Single 4KiB random write process        	local                                             	0 B/s     	4.4 MB/s   	0 IOPS     	1.1 kIOPS   	0s ± 0s                   	702.357µs ± 359.925µs     	0s ± 0s                
Single 4KiB random write process        	Tart                                              	0 B/s     	2.6 MB/s   	0 IOPS     	656.37 IOPS 	0s ± 0s                   	1.140086ms ± 1.450472ms   	0s ± 0s                
Single 4KiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	2.7 MB/s   	0 IOPS     	677.07 IOPS 	0s ± 0s                   	1.179872ms ± 1.219626ms   	0s ± 0s                
Single 4KiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	3.3 MB/s   	0 IOPS     	832.66 IOPS 	0s ± 0s                   	948.648µs ± 94.141338ms   	0s ± 0s                
Single 4KiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	15 MB/s    	0 IOPS     	3.65 kIOPS  	0s ± 0s                   	260.717µs ± 19.977757ms   	0s ± 0s                
16 parallel 64KiB random write processes	local                                             	0 B/s     	9.5 GB/s   	0 IOPS     	147.89 kIOPS	0s ± 0s                   	753.289µs ± 8.028974ms    	0s ± 0s                
16 parallel 64KiB random write processes	Tart                                              	0 B/s     	10 GB/s    	0 IOPS     	176.96 kIOPS	0s ± 0s                   	429.83µs ± 33.792264ms    	0s ± 0s                
16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none")               	0 B/s     	12 GB/s    	0 IOPS     	180.89 kIOPS	0s ± 0s                   	383.524µs ± 17.524971ms   	0s ± 0s                
16 parallel 64KiB random write processes	Tart (--root-disk-opts="caching=cached")          	0 B/s     	336 MB/s   	0 IOPS     	5.24 kIOPS  	0s ± 0s                   	9.970844ms ± 365.808663ms 	0s ± 0s                
16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	9.4 GB/s   	0 IOPS     	147.04 kIOPS	0s ± 0s                   	524.139µs ± 34.100009ms   	0s ± 0s                
Single 1MiB random write process        	local                                             	0 B/s     	178 MB/s   	0 IOPS     	173.36 IOPS 	0s ± 0s                   	3.835103ms ± 2.917977ms   	0s ± 0s                
Single 1MiB random write process        	Tart                                              	0 B/s     	140 MB/s   	0 IOPS     	136.48 IOPS 	0s ± 0s                   	4.721178ms ± 7.744965ms   	0s ± 0s                
Single 1MiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	144 MB/s   	0 IOPS     	140.63 IOPS 	0s ± 0s                   	4.443507ms ± 11.572454ms  	0s ± 0s                
Single 1MiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	47 MB/s    	0 IOPS     	45.55 IOPS  	0s ± 0s                   	13.267881ms ± 358.283094ms	0s ± 0s                
Single 1MiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	196 MB/s   	0 IOPS     	191.4 IOPS  	0s ± 0s                   	4.102516ms ± 73.117503ms  	0s ± 0s                
Random reads/writes (4k)                	local                                             	8.7 MB/s  	8.7 MB/s   	2.16 kIOPS 	2.16 kIOPS  	193.370794ms ± 42.593607ms	222.272016ms ± 56.586971ms	0s ± 0s                
Random reads/writes (4k)                	Tart                                              	4.1 MB/s  	4.1 MB/s   	1.02 kIOPS 	1.03 kIOPS  	31.038867ms ± 13.508668ms 	31.184305ms ± 14.032766ms 	0s ± 0s                
Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none")               	4.2 MB/s  	4.2 MB/s   	1.04 kIOPS 	1.05 kIOPS  	30.368422ms ± 13.505627ms 	30.595412ms ± 13.840944ms 	0s ± 0s                
Random reads/writes (4k)                	Tart (--root-disk-opts="caching=cached")          	2.2 MB/s  	2.2 MB/s   	545.33 IOPS	548.86 IOPS 	59.31316ms ± 716.351086ms 	57.647852ms ± 711.503882ms	0s ± 0s                
Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none,caching=cached")	6.0 MB/s  	6.0 MB/s   	1.5 kIOPS  	1.5 kIOPS   	21.244222ms ± 47.808399ms 	21.39459ms ± 44.716307ms  	0s ± 0s                
```

--------------------------------

### Create a new Orchard Controller context with a specific port

Source: https://github.com/openai/tart/blob/main/docs/orchard/using-orchard-cli.md

Configure a new context to communicate with an Orchard Controller on a non-default port.

```shell
orchard context create orchard-controller.example.com:8080
```

--------------------------------

### Mount Host Directory Read-Only to VM

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Runs a VM named 'vm' and mounts the host directory '~/src/project' as 'project' in read-only mode. Requires macOS 13.0 (Ventura) or newer.

```bash
tart run --dir=project:~/src/project:ro vm
```

--------------------------------

### Enable Debugging Output for FIO Benchmark

Source: https://github.com/openai/tart/blob/main/benchmark/README.md

Runs the FIO benchmark with debugging output enabled. This is useful for diagnosing issues during the benchmarking process.

```shell
go run cmd/main.go fio --debug
```

--------------------------------

### Tart Guest Agent Configuration Options

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2025-06-01-tart-guest-agent.md

The Tart Guest Agent can be configured with various flags to enable specific functionalities. These flags determine whether the agent runs as a daemon or agent, and which features like disk resizing, clipboard sharing, or RPC are enabled.

```bash
--resize-disk — resizes the disk when there's a free space at the end of a disk (assuming that one previously ran `tart set --disk-size`)
```

```bash
--run-vdagent — clipboard sharing
```

```bash
--run-rpc — `tart exec` and new functionality in the future
```

```bash
--run-daemon (which implies `--resize-disk`)
```

```bash
--run-agent (which implies both `--run-vdagent` and `--run-rpc`)
```

--------------------------------

### Login to a Tart Registry

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Log in to a specific Tart registry. This command is necessary before pushing or pulling images.

```bash
tart login acme.io
```

--------------------------------

### Create Service Account for Worker Pool

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-workers.md

Creates a service account with compute read and write roles for worker functionality.

```bash
orchard create service-account worker-pool-m1 --roles "compute:read" --roles "compute:write"
```

--------------------------------

### Packer Template for Local VM Image Build

Source: https://github.com/openai/tart/blob/main/docs/integrations/packer.md

This Packer template configures the Tart builder to create a local VM image based on a remote OCI image. It specifies required plugins, source VM details, and shell provisioners for customization.

```hcl
packer {
  required_plugins {
    tart = {
      version = ">= 0.5.3"
      source  = "github.com/cirruslabs/tart"
    }
  }
}

source "tart-cli" "tart" {
  vm_base_name = "ghcr.io/cirruslabs/macos-tahoe-base:latest"
  vm_name      = "my-custom-tahoe"
  cpu_count    = 4
  memory_gb    = 8
  disk_size_gb = 70
  ssh_password = "admin"
  ssh_timeout  = "120s"
  ssh_username = "admin"
}

build {
  sources = ["source.tart-cli.tart"]

  provisioner "shell" {
    inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
  }

  # more provisioners
}
```

--------------------------------

### List Physical Disks

Source: https://github.com/openai/tart/blob/main/docs/faq.md

Run this command within a VM to identify physical disks and APFS containers. It helps in determining which partitions to manipulate.

```shell
diskutil list physical
```

--------------------------------

### Create Static IP Address for Orchard Controller

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Creates a static IP address in the us-central1 region for the Orchard Controller instance. The IP address is then exported to the ORCHARD_IP environment variable.

```bash
gcloud compute addresses create orchard-ip --region=us-central1
export ORCHARD_IP=$(gcloud compute addresses describe orchard-ip --format='value(address)' --region=us-central1)
```

--------------------------------

### Profile Tart Pull with xctrace(1)

Source: https://github.com/openai/tart/blob/main/PROFILING.md

Record a CPU profile of a `tart pull` command using `xctrace record`. This command generates a `.trace` file that can be analyzed with Instruments for detailed performance insights.

```shell
xctrace record --template "CPU Profiler" --target-stdout - --launch -- /opt/homebrew/bin/tart pull ghcr.io/cirruslabs/macos-tahoe-base:latest
```

--------------------------------

### Controller gRPC Service Definition

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2024-06-20-jumping-through-the-hoops.md

Defines the minimalistic gRPC service that the Orchard controller offers for worker communication. It includes methods for watching instructions and managing port-forwarding streams.

```protobuf
service Controller {
  rpc Watch(google.protobuf.Empty) returns (stream WatchInstruction);
  rpc PortForward(stream PortForwardData) returns (stream PortForwardData);
}
```

--------------------------------

### Watch Instruction Action Types

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2024-06-20-jumping-through-the-hoops.md

Defines the possible actions within a watch instruction from the controller to a worker. These include requests for port-forwarding or VM synchronization.

```protobuf
oneof action {
  PortForward port_forward_action = 1;
  SyncVMs sync_vms_action = 2;
}
```

--------------------------------

### Clone and Run Sonoma VM in Suspendable Mode

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2023-09-20-tart-2.0.0.md

Clone a macOS Sonoma base image and run it in suspendable mode. This mode allows for VM snapshotting, enabling faster startup times by resuming from a snapshotted state. Requires both host and guest to be running macOS Sonoma.

```bash
tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base
tart run --suspendable sonoma-base
```

--------------------------------

### Mount Shared Directory in Linux Guest

Source: https://github.com/openai/tart/blob/main/docs/quick-start.md

Manually mounts the virtual filesystem for shared directories to '/mnt/shared' within the Linux guest VM.

```bash
sudo mkdir /mnt/shared
sudo mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared
```

--------------------------------

### Kubernetes Resources for Orchard Controller Deployment

Source: https://github.com/openai/tart/blob/main/docs/orchard/deploying-controller.md

Deploys Orchard Controller on Kubernetes using a PersistentVolumeClaim for storage, a StatefulSet for the controller, and a Service of type LoadBalancer for external access. This configuration ensures persistent storage and simplifies network exposure.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: orchard-controller
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  # Uncomment this when deploying on Amazon's EKS and
  # change to the desired storage class name if needed
  # storageClassName: gp2
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: orchard-controller
spec:
  serviceName: orchard-controller
  replicas: 1
  selector:
    matchLabels:
      app: orchard-controller
  template:
    metadata:
      labels:
        app: orchard-controller
    spec:
      containers:
        - name: orchard-controller
          image: ghcr.io/cirruslabs/orchard:latest
          volumeMounts:
            - mountPath: /data
              name: orchard-controller
      volumes:
        - name: orchard-controller
          persistentVolumeClaim:
            claimName: orchard-controller
---
apiVersion: v1
kind: Service
metadata:
  name: orchard-controller
spec:
  selector:
    app: orchard-controller
  ports:
    - protocol: TCP
      port: 6120
      targetPort: 6120
  type: LoadBalancer
```

--------------------------------

### Orchard CLI: Executing Script on VM via SSH

Source: https://github.com/openai/tart/blob/main/docs/blog/posts/2023-04-28-orchard-ssh-over-grpc.md

Sends a local script for execution on the specified VM using SSH redirection. The VM will execute the script received via standard input.

```shell
orchard ssh vm sonoma-builder 'sh -s' < script.sh
```

--------------------------------

### Authenticate API Calls in Golang

Source: https://github.com/openai/tart/blob/main/docs/orchard/integration-guide.md

This Golang snippet demonstrates how to authenticate with the Orchard API. The client automatically reads the current user's Orchard context.

```go
package main

import (
  "context"
  "fmt"
  "github.com/cirruslabs/orchard/pkg/client"
  "log"
)

func main() {
  client, err := client.New()
  if err != nil {
    log.Fatalf("failed to initialize Orchard API client: %v", err)
  }

  controllerInfo, err := client.Controller().Info(context.Background())
  if err != nil {
    log.Fatalf("failed to retrieve controller's information: %v", err)
  }

  fmt.Println(controllerInfo.Version)
}
```