Hosting a local GNS3 server inside an OrbStack Linux machine on Apple Silicon offers a flexible networking lab environment, though it introduces a few key constraints:

  • No x86_64 KVM virtualization: Hardware acceleration is unavailable for nested x86_64 VMs.
  • Emulation overhead: Running x86_64 Linux binaries relies on Rosetta emulation, introducing a slight performance penalty.
  • Network limitation: OrbStack uses a custom-built virtual network stack that does not support bridged networking . The Cloud and NAT nodes will not function.

Note: QEMU and libvirt are disabled due to these constraints.

Despite these limitations, a broad range of network devices operate reliably:

Device Supported Notes
Cisco IOL/IOL L2 ✅ Native/emulated lightweight execution of Cisco IOS-XE
Dynamips ✅ Ideal for legacy Cisco IOS images
VPCS ✅ Simple PC emulator with a minimal resource footprint
Docker Containers ✅ ARM64 or x86_64 (Rosetta)

In practice, CPU overhead is rarely the bottleneck. The amount of available unified memory on your Mac will usually dictate topology limits. And let’s face it: connecting to a dedicated x86_64 GNS3 compute server with ample CPU cores and RAM is the ideal solution for running large labs.

On the other hand, having the ability to spin up a 20-node CCIE route and switch topology entirely on your portable MacBook makes this setup well worth the effort.

Prerequisites

Steps

  1. Download OrbStack and open it.

An OrbStack Linux machine with seamless Rosetta integration is the magic sauce for hosting our GNS3 server and components.

  1. Open your favorite terminal emulator.

We will work from the command line for most of the following steps.

  1. Change to the Documents directory.
cd ~/Documents
  1. Clone the gns3-server-orbstack repo from GitHub.
git clone https://github.com/mweisel/gns3-server-orbstack.git
  1. Change to the gns3-server-orbstack directory.
cd gns3-server-orbstack
  1. Create a Python virtual environment for Ansible.
uv sync
  1. Verify Ansible is installed.
uv run ansible --version
  1. Start OrbStack (if not already started).
orb status || orb start
  1. Create the gns3 Linux machine.
orb create ubuntu:resolute gns3
  1. Verify the gns3 Linux machine is listed and in a running state.
orb list

output:

NAME  STATE    DISTRO  VERSION   ARCH   SIZE      IP
----  -----    ------  -------   ----   ----      --
gns3  running  ubuntu  resolute  arm64  623.6 MB  192.168.139.237
  1. Test Ansible connectivity to the gns3 Linux machine.
uv run ansible all -m ping

output:

gns3@orb | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python3.14"
    },
    "changed": false,
    "ping": "pong"
}
  1. Deploy the latest stable release of GNS3 server and components.
uv run ansible-playbook server.yml

Sit back and relax. The automated process should take less than 8 minutes to complete.

  1. Check availability after the Ansible playbook completes.

Verify the GNS3 server is up and ready with a HTTP GET request.

curl -s http://gns3.orb.local:3080/v3/version
  1. (WebUI) Open the GNS3 WebUI with your default web browser.
open http://gns3.orb.local:3080
  1. (GUI) Attach your GNS3 client to the GNS3 server.
    GNS3 server preferences

    1. Open the GNS3 client application.

    2. Click the Settings button.

    3. Select Controller on the left side menu.

    4. Select the Controller tab.

    5. Enter the following values for the Remote controller section:

      • Protocol: HTTP
      • Host: gns3.orb.local
      • Port: 3080 TCP
      • Username: admin
      • Password: admin

    6. Click the Connect button to test the connection to the controller.

      Test controller connection

    7. Click the Apply button to save the configuration.

    8. Click the OK button to close the Preferences window.

Workflow

  1. Start OrbStack from the command line or open the OrbStack GUI.
orb status || orb start
  1. Start the gns3 Linux machine from the command line or the OrbStack GUI.
orb start gns3

  1. Open the GNS3 client application or WebUI.

  2. Create (or open) a project.

  3. Start the devices.

  4. Happy Labbing!

  5. Save the configuration at the device-level (e.g., copy run start, wr mem, etc.).

  6. Stop the devices.

  7. Close the GNS3 client application.

  8. Stop the gns3 Linux machine from the command line or the OrbStack GUI.

orb stop gns3

Q&A

  1. How do I install a specific GNS3 server version?

The Ansible playbook will install the latest stable version by default. You can override this by explicitly setting the gns3_version variable.

uv run ansible-playbook server.yml -e 'gns3_version=3.0.5'
  1. How do I display the gns3server log to aid in troubleshooting?
orb -m gns3 journalctl -u gns3 -f