> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Building a hardened custom image

> Build an Orka VM image with your own security tooling baked in: EDR, DLP, or MDM agents. Covers the deploy, install, validate, and save workflow for AWS and on-prem deployments.

If you run compliance-sensitive workloads, you likely need your endpoint security stack (EDR, DLP, or MDM agents) present on every VM your team deploys, not installed by hand after the fact. This page walks through building that image once and reusing it.

Building your own image is where MacStadium's shared responsibility model hands off to you: MacStadium secures the host AMI, the physical hardware, and the Orka platform itself. What runs inside your guest VM, including whatever security tooling you bake into it, is yours to build and secure. This page is how you exercise that side of the split.

<Note>
  This page is about **your own** hardened guest image, the macOS VM disk image your team deploys from. It's not about MacStadium's Orka host AMI, the underlying EC2 Mac instance image that runs Virtual Kubelet and Orka Engine. MacStadium builds and shares that AMI with your AWS account as part of your deployment; you don't build or modify it. If you're looking for that instead, see [Getting started with Orka on AWS](/orka/orka-on-aws-and-on-prem/orka-on-aws-getting-started).
</Note>

## Overview

Building a hardened image follows the same [OCI image workflow](/orka/oci-images/oci-images-overview) as any other custom image: deploy a base VM, make your changes, then save or push the result as a new image. The only difference is what you install and one important rule about identity.

1. Deploy a VM from a base image.
2. Connect and install your security tooling.
3. Verify the tooling is present and working.
4. Save or push the VM as a new image.
5. Deploy your team's VMs from that image going forward.

## Before you start

* An orka3 CLI session with permission to deploy VMs in your namespace. See [Orka CLI quick start](/orka/quick-start-guides/orka3-cli-quick-start) if you need to install it.
* The installer packages for your security tools (Rapid7, CrowdStrike, Jamf Protect, Microsoft Defender, Jamf Pro, or your own equivalents).
* If you're pushing to a private registry instead of saving locally, [registry credentials configured in your namespace](/orka/oci-images/oci-images-manage-registry-credentials).

## 1. Deploy a base VM

Start from one of the [official vanilla macOS images](https://github.com/macstadium/orka-images), or your team's existing base image if you already have one.

```bash theme={null}
orka3 vm deploy hardened-image-build --image ghcr.io/macstadium/orka-images/sequoia:latest
```

Get the VM's connection details:

```bash theme={null}
orka3 vm list hardened-image-build --output wide
```

Connect via Screen Sharing at `vnc://<VM_IP>:<Screenshare_port>` (default credentials: `admin`/`admin`).

## 2. Install your security tooling

Install each package. Most enterprise security tools support unattended installation, which is faster and more repeatable than installing through the GUI:

```bash theme={null}
sudo installer -pkg /path/to/your-agent.pkg -target /
```

<Warning>
  Don't complete device enrollment inside the build VM. If you finish Jamf Pro enrollment or let an EDR agent generate its device/sensor ID before saving the image, every VM you later deploy from that image inherits the same device record. Your management console will show duplicate or conflicting entries the moment more than one VM is running. Install the agent packages, but let enrollment and identity generation happen at first boot on each deployed VM, not in the build image.
</Warning>

## 3. Verify the tooling

Before saving, confirm each tool is actually present and functioning as expected, not just installed. At minimum:

* The agent process is running (`ps aux | grep <agent>` or the tool's own status command).
* The agent's local logs show no errors from the install.
* If the tool has a lightweight local check (a CLI status command, a menu bar icon reporting healthy), use it.

Don't rely on the management console showing the device as registered. Per the warning above, you're deliberately not completing enrollment yet.

## 4. Save or push the image

If you're keeping the image on this cluster only:

```bash theme={null}
orka3 vm save hardened-image-build my-team-hardened-sequoia
```

If your team works across multiple clusters or you want version history, push to your registry instead (Apple silicon nodes only):

```bash theme={null}
orka3 vm push hardened-image-build <SERVER_ADDRESS>/<IMAGE>:<TAG>
```

<Note>
  `vm push` authenticates against the Orka API server, not the registry, even though the error can look registry-related. If you see `Unauthorized`, run `orka3 login` (or `orka3 user set-token`) to refresh your Orka API token before retrying.
</Note>

Both operations are async. Check status with:

```bash theme={null}
orka3 image list my-team-hardened-sequoia --output wide
```

See [Preserve changes](/orka/oci-images/oci-images-preserve-changes) for the full command reference, including the Orka API equivalents.

## 5. Clean up and deploy

Delete the build VM once the image save or push completes:

```bash theme={null}
orka3 vm delete hardened-image-build
```

Deploy your team's VMs from the new image:

```bash theme={null}
orka3 vm deploy --image my-team-hardened-sequoia
```

Each deployed VM completes MDM/EDR enrollment independently at first boot, so your management console sees distinct, correctly identified devices.

## Deploying at scale

If your team deploys many VMs from this image, pre-cache it on your nodes (Apple silicon only) so new deployments don't wait on a fresh pull:

```bash theme={null}
orka3 imagecache add my-team-hardened-sequoia --all
```

## Keeping the image current

Security tooling updates on its own schedule, independent of Orka or macOS releases. Repeat this workflow whenever you need to bump agent versions or add a new tool, and save under a new tag (`my-team-hardened-sequoia-v2`) rather than overwriting the image your team is actively deploying from, so you can roll back if the new build has issues.


## Related topics

- [Orka VM Tools for guest services on ARM VMs](/orka/orka-resources/vm-tools.md)
- [Citrix DaaS configuration](/remote-desktop-vdi/configuration/citrix-daas-configuration.md)
- [Packer plugin for automated Orka image builds](/orka/orka-devops-integrations/packer.md)
- [VDI golden image management](/remote-desktop-vdi/configuration/image-management.md)
- [Bazel Remote Build Execution with Orka](/orka/orka-devops-integrations/bazel-rbe.md)