For development, CloudCaptain can run your Apps on VirtualBox.


  • dev

Supported Versions

CloudCaptain supports VirtualBox 5.0.x, 5.1.x and 5.2.x running on Windows, Mac OSX or Linux.

Hyper-V compatibility (Windows Users only)

Due to the way Hyper-V is architected, VirtualBox will no longer work if Hyper-V is enabled. In that case, you can either switch to CloudCaptain's support for Hyper-V or disable Hyper-V to make VirtualBox work again.

CPU & RAM usage

You can control the number of CPUs exposed to the VM using the cpus property and the number of MB of RAM using the ram property. By default, CloudCaptain assigns 2 CPUs and 1024 MB of RAM to the Instance.


By default CloudCaptain uses regular VirtualBox NAT where each instance has its own network and is assigned the exact same IP address. Instances do have the possibility to communicate with each other, albeit only via forwarded ports (see below) on the gateway.

VirtualBox 5.1+ users also have the possibility to let CloudCaptain use a NAT Network instead of regular VirtualBox NAT by explicitly setting the virtualbox.natnetwork CloudCaptain configuration property to true. CloudCaptain then creates a separate VirtualBox NAT Network and all CloudCaptain instances are automatically assigned their own IP address via DHCP in the range on that network and can communicate with each other directly using their respective addresses. This is great for microservices and client-side load balancing with Eureka.

Port forwarding

To access the apps running on your VirtualBox instances from your physical machine, the ports of the instances must be forwarded to ports of your physical machine. CloudCaptain does this automatically for you for any port defined in the image of the instance.

By default CloudCaptain tries to expose the same port on your physical machine as was exposed on your instance. This means that if your instance has a service that listens to HTTP on TCP port 8080 of your instance, CloudCaptain will then also attempt to make it available at localhost:8080 on your physical machine. If this port is occupied, CloudCaptain will automatically select the next available port and use that instead.

You can also customize the port forwarding using the portsmap.NAME=HOST_PORT_NUMBER properties.

Example: Say you have a webserver running as port 80 within the VM and would like to be able to reach it using port 4444 on your physical machine you would configure CloudCaptain like this:

> boxfuse run myapp.jar -ports.http=80 -portsmap.http=4444

Accessing services running on the physical host

To make it easy to access services running on your physical machine (outside of your CloudCaptain VirtualBox instance), CloudCaptain exposes an environment variable named BOXFUSE_HOST_IP to each of its VirtualBox instances. This environment variable contains the IP address of your physical machine (example: which you can use this to construct URLs to access your services.

AWS Credentials

To make it easy to access AWS services from your VirtualBox instances, CloudCaptain automatically exposes the AWS credentials stored by the AWS CLI on your local machine to the running instances.

CloudCaptain will attempt to load credentials in the following order:

  1. The boxfuse profile in ~/.aws/credentials
  2. The default profile in ~/.aws/credentials
  3. The default section in ~/.aws/config

You can also manually override this by explicitly setting the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.