On-Box Python: Scripting IOS XE from the Inside

Off-box automation - a Python script on a server driving routers over SSH - is where most network automation lives, and rightly so. But it has one structural weakness: it depends on the automation host being reachable. If the management network is down, or the site is isolated, the automation cannot run. On-box Python removes that dependency by putting the script on the device, where it can react to local conditions no matter what the rest of the network is doing.

This article covers on-box Python on IOS XE - the models, the cli module, and where it runs - with the honest platform picture and a fully-captured off-box pipeline as the real, working reference. It extends the network automation guide.

The two on-box models

Both use the same key primitive: the cli module, which is Python's window into IOS.

The cli module: Python's bridge to IOS

The cli module (available in the on-box Python environment) provides functions that run IOS commands and hand you the result as a Python string you can parse:

from cli import cli, clip, configure, execute

# Read operational state
routes = cli('show ip route')            # returns the output as a string
clip('show ip interface brief')          # runs it AND prints it

# Make configuration changes
configure(['interface Loopback99',
           'ip address 10.99.99.99 255.255.255.255',
           'no shutdown'])

# Execute an exec command
execute('write memory')

This is what makes on-box Python powerful: your script has the full expressiveness of Python - loops, conditionals, regex, data structures, external libraries - and can drive the device's configuration and read its state through cli. A script can pull the routing table, parse it, decide something, and reconfigure - all on the box.

The natural pairing: EEM + on-box Python

On-box Python's killer combination is with EEM. An EEM applet detects an event (a syslog message, an SNMP threshold, an interface state change) and, as one of its actions, launches an on-box Python script:

event manager applet HIGH-CPU-CAPTURE
 event snmp oid 1.3.6.1.4.1.9.9.109.1.1.1.1.7.1 get-type exact entry-op ge entry-val 90 poll-interval 10
 action 1.0 cli command "guestshell run python /flash/capture_diag.py"

Now the router responds to high CPU by running a Python script that captures diagnostics, all autonomously, with no external system involved. That is the pattern on-box Python exists for: local, autonomous reaction to local events. The router self-manages.

The honest platform picture

On-box Python needs the same foundation as Guest Shell - IOx on a full IOS XE platform. And as covered in the Guest Shell article, the lightweight virtual IOS (IOL) used for our fast routing labs does not have it: iox is an invalid command, so there is no on-box Python environment to enter. The heavier virtual platforms that do have the app-hosting stack have their own DMI-initialisation issues in a lab.

Rather than fabricate on-box Python output on a platform that cannot produce it, we show you the real, captured thing: the off-box Python pipeline that does the same work from an external host, verified end to end on a live device.

The real, captured alternative: off-box Python with Netmiko

From the lab, a Python script on the Linux host drove a real IOS XE router over SSH - rendering config, pushing it, and reading back the device state to verify. The push result and the verification, both real:

=== NETMIKO PUSH RESULT (from the automation host) ===
R1(config-router)# network 172.20.100.0 0.0.0.255 area 0
R1(config-router)# network 172.20.101.0 0.0.0.255 area 0
R1(config-router)#end

=== DEVICE VERIFICATION (pulled back via the same script) ===
Loopback100  172.20.100.1  YES manual up  up
Loopback101  172.20.101.1  YES manual up  up
Lo100  10  0  172.20.100.1/24  1  LOOP
Lo101  10  0  172.20.101.1/24  1  LOOP

The Python here - ConnectHandler, send_config_set, send_command - is the off-box equivalent of the cli module's configure and cli functions. The logic of "read state, decide, configure, verify" is identical; only the location of the script differs. This is the model you will use for the overwhelming majority of automation, and it works on every platform.

On-box vs off-box: the decision

1. Managing many devices from one place, version-controlled, in a pipeline? Off-box. Always. This is 95% of automation.
2. A device that must react to a local event with no dependency on an external system (an isolated site, a self-healing edge)? On-box, launched from EEM. This is the real niche.
3. A one-off diagnostic that needs to run on the box during an event (capture state the moment CPU spikes)? On-box, because by the time you SSH in the moment has passed.
4. Anything where the automation host is reliably reachable? Off-box. It is simpler, more scalable, and platform-independent.

Key takeaways

• On-box Python runs a script on the router, removing the dependency on an external automation host - powerful for autonomous local reactions.
• The cli module is the bridge: cli() / clip() to read state, configure() to make changes, from inside Python on the device.
• Its killer pairing is EEM + on-box Python: an event triggers a Python script that responds autonomously, with no external system.
• It needs IOx on a full IOS XE platform. IOL (our lightweight lab image) has no iox, so we describe it honestly and show the real off-box equivalent rather than faking output.
• The captured, working reference is off-box Python with Netmiko - the same read/decide/configure/verify logic, from an automation host, verified on a live device.
• Off-box is the default for almost everything. On-box is a specialist tool for genuine local autonomy.

Next: Jinja2 templates for network configs - from variables to rendered CLI, the fully-captured pipeline. The full cluster index lives on the network automation pillar.