Customers can create & upload their own Machines, which can be spawned along with other content in the Dedicated Labs line-up. This Machine gives points, badges and achievements, just like other Hack The Box content, and works seamlessly in the fully gamified training environment of the Dedicated Labs.
Our team will work alongside you on the system requirements, consult with you on the Machine preparation steps, and test the virtual machine's final image to ensure that it is fully functional before being uploaded on our infrastructure and, subsequently, your Dedicated Lab environment.
Before proceeding, make sure your custom machine meets the following criteria:
The Machine image can be an OVA file (for virtual machines) or a Docker image.
The image size should not exceed 40GB.
The Machine should have a clear user flag and root flag.
Eligible Plans: Dedicated Labs Professional and All Bundles except for Lite.
Preparing Your Machine
Step 1: Setting up the Machine Image
You can choose to submit an OVA file or a Docker image.
OVA Files: These are typically used for VirtualBox or VMware. Ensure your virtual machine is properly configured and exported as an OVA file.
Docker Images: If you're using Docker, ensure your Docker image is properly built.
Step 2: Integrating User and Root Flags
Ensure your Machine has a clear user flag and a root flag integrated. These flags serve as milestones for the users to confirm they've successfully exploited a part of the system.
Submitting Your Machine
Once your Machine is set up and meets all the criteria, you're ready to submit it for review.
Step 1: Compressing the Image
Before submitting, compress your Machine image to ensure it is in a respectable size to share.
Linux
For Linux, we recommend the following tools be used:
bzip2: This is a common tool on Unix-based systems. It typically achieves better compression ratios than gzip but is slower. The command to compress a file using bzip2 is
bzip2 filename.xz: This tool uses the LZMA/LZMA2 algorithms, which typically achieve the best compression ratios, but it is slower than gzip and bzip2. The command to compress a file using xz is
xz filename.
Windows
For Windows, we recommend the following tools be used:
7-Zip: This is a free and open-source tool that supports a variety of compression formats. It's known for its high compression ratio, especially when using the 7z format with the LZMA/LZMA2 algorithm.
WinRAR: This is a trialware file archiver with a high compression ratio. It supports RAR and ZIP formats, but you can also unpack various other formats.
Step 2: Sending the Image
Email the Machine image to [email protected]. In your email, provide a brief description of the machine, including its purpose, any special features, and the intended level of difficulty.
Step 3: Awaiting Review
After submitting, your Machine will be reviewed by the Hack The Box team. They will check for any issues and may contact you for further information or clarification.
The limit to the number of Custom Machines usually ranges between 1 and 4 Custom Machines per annual Professional and Ultimate subscription.
Updating Your Machine
Once your machine has been imported and configured in our infrastructure, please follow the instructions below for any future updates.
1. Avoid Resubmitting OVA/OVF for Minor Updates After the initial import, your machine becomes part of our managed infrastructure.
While it’s possible to re-import a new OVA/OVF, doing so requires our content team to repeat several manual steps — including networking adjustments, disk size reduction, and compatibility checks.To keep the process efficient, we recommend using Docker or direct file updates for subsequent changes, especially when your machine primarily runs a web application.
2. Use Docker for Web-Based Machines (Recommended) If your update involves application or service-level changes:
- Package the updated application as a Docker image or provide a Dockerfile.
- Clearly tag your image (e.g., challenge_name:v1.1).
- Include short deployment notes if there are new environment variables, ports, or dependencies.
- Our content team will:
- Pull and deploy your updated image inside the existing machine.
- Validate that everything works properly within the HTB environment. This is the fastest and most reliable way to push updates without repeating the full import process.
3. For Small Code Updates If only the web application’s source code has changed (no Docker or OS modifications):
- Share the updated files or codebase directly.
- The content team will replace the old code in the existing machine.
- We’ll verify the service functionality and scoring integration after deployment.
4. When a New OVA/OVF Is Needed
If your update includes major OS-level changes, new system dependencies, or fundamental configuration differences, please contact us before preparing a new OVA/OVF.
Our team will confirm whether a fresh import is required and guide you through the process.