CORE WORKFLOWS

Change safety

Understand the two-check approval model, snapshots, verification, rollback limits, and the safest way to make a first change.

Verified against AI NetShell 0.4.15

Purpose#

Understand what AI NetShell checks, what can run automatically, what always needs your approval, and what recovery can and cannot do before you apply a configuration change.

Before You Begin#

For your first change:

• Start on authorized lab equipment. If a lab is not available, use equipment in a maintenance window.
• Assign a least-privilege device Credential that can make only the intended change.
• Keep an independent recovery path, such as console or out-of-band management.
• Confirm the target device and current session.
• Verify that the approval preview contains a captured before state and recovery method before applying.

Steps#

1. Know what can run without a click#

The Read approval setting under Settings > General controls the read-only commands requested by Lina, the AI NetShell assistant:

Automatic reads are not automatic configuration changes. Enabling automatic reads never removes the separate approval required for a write.

Sending any configuration change also needs Allow configuration changes, in the Configuration changes row of Settings > General. It is off by default, so a new installation cannot send a change until you turn it on. Its note reads: "Off by default. Each change still shows a diff for your approval on every device. Switching this is recorded in the audit log." The switch never approves a change for you. It only decides whether this PC may send a change after you approve it. If the app could not open its audit log when it started, the switch cannot be turned on until a restart succeeds in opening the log.

2. Understand the two checks#

The approval card shows the result of the first check as Checks passed: valid commands, allowed by your write policy. The line under its title reads Your approval applies this change to device.

The two checks are:

1. AI NetShell checks the complete proposed change against the selected device's write policy and prepares the approval preview.
2. You review the exact device, intent, the before-and-after change, risk, recovery information, and before state, then deliberately approve or cancel.

A successful policy check cannot approve its own change. Your approval cannot override a failed policy check.

3. Review the preview and snapshot#

Before approval, inspect:

• The target device and active session
• Every added and removed line in the current and after change comparison
• The recorded intent
• The risk, such as Low risk · adds config, and what happens If the check fails
• The checks result and any management-path warning
• The captured before state, under Technical details
• The recovery method and undo information
• Any high-impact or destructive-change warning

The governed flow captures a redacted configuration snapshot of the before state when it builds the preview, before anything is applied. If that capture fails, for example on a timeout or a dropped session, the proposal stops with an error instead of showing a preview against a before state that was never read. Do not continue until you have confirmed the device state and a usable recovery plan.

Keep these records distinct:

• The pre-change snapshot is a redacted point in the config time machine. It supplies the before state, the before-and-after change, drift attribution, and later comparison.
• The rollback anchor is the platform-specific recovery preparation. Depending on the platform, it can be a saved configuration, named checkpoint, native rollback history, targeted inverse, or timed revert. A targeted inverse undoes an added object by deleting exactly that object.
• An Active Discovery backup is a separate restore-grade discovery capture stored encrypted in Config & Compliance. It is not proof that remote rollback will work.

The write plan prepares its available rollback anchor before it sends the approved configuration statements. The review card describes the method for that proposal.

4. Understand the protections around a change#

AI NetShell applies these capability-level protections to changes Lina proposes:

• It checks the complete ordered proposal for the selected platform before anything reaches the device.
• It refuses unsupported or disallowed actions rather than letting Lina bypass the device policy.
• It binds the approval to the current target, proposal, and session, then rechecks that context before apply.
• It shows the exact before-and-after change. Only you can approve a proposal from Lina.
• It adds a typed device-name confirmation for high-impact changes. Shutting down an interface or VLAN that is up is one of these: it is rated Medium risk · changes traffic and shows a red warning that names what goes down.
• It records the intent, approval, result, and verification state in the local change and audit records.
• It captures a redacted pre-change point and, when snapshot storage succeeds, retains it in Config & Compliance, where later captures can show whether an interval has a governed pre-change capture or is unexplained.

These protections do not govern commands you personally type in the terminal. Treat terminal access as direct administrative access.

Only one task types on a device session at a time. A change or a rollback holds the session from its first line to its last cleanup line, and the app's checks and Lina's reads wait for it. Do not type in the device's terminal while AI NetShell applies or rolls back a change on it. The app does not stop you, and your typing can make the change stop part way.

5. Apply and verify#

After approval, keep the terminal and change card visible. The app reports whether the device accepted the change, then compares fresh reads with the pre-change baseline and intended outcomes.

Interpret the result precisely:

• Intended outcomes verified means the configured checks passed.
• A result that says the change was applied but verification is incomplete means the app could not prove the intended result.
• A device error, timeout, dropped session, or incomplete record is not a successful verification.
• A Manual change is a fix whose result AI NetShell cannot check after a change, such as HSRP settings. The approval card says so before you approve. After it is applied, it is not marked verified. Check the device yourself, then select Keep without the check or Roll back.

Independently test reachability and the service affected by the change. Verification covers the checks available to the app, not every possible operational effect.

On Cisco IOS, IOS XE, NX-OS, and Arista EOS, an applied change is in the running configuration only, and a reload undoes it until it is saved. The app does not save it by itself, and Lina cannot save. After the change passes its check, Save Changes saves the device's whole running configuration, including anything changed by hand since the last save. It asks first, and the app reports the change as saved only when the device confirms it. See Resolve.

6. Use rollback carefully#

When a recovery method is available, the applied-change card keeps Roll back available. Some platforms use a saved configuration or checkpoint; others use platform-native or timed recovery behavior. The card describes the method for that proposal. A fix that covers several interfaces of one device is approved once, and it is applied, checked, and rolled back as one change.

In the Changes list, every Roll back asks first and says what will happen. An older change with a newer one on the same device is refused, not rolled back, and the message names the newer change. A finding marked Fixed opens again when its change is rolled back.

On Cisco IOS, IOS XE, NX-OS, and Arista EOS, a rollback changes the running configuration only. If you saved the change to the startup configuration, save again after the rollback, or a reload brings the change back. The app says so. Until the app restarts, Save Changes lets you save the rollback too.

Timed auto-revert is not a universal Resolve timer. It is the FortiOS recovery method for supported modification shapes: AI NetShell sets a five-minute device-side timer before apply, and Keep the change sends the save sequence that makes the change permanent. If Keep the change is not selected or cannot be sent before the deadline, FortiOS reboots to its last saved configuration. Additive FortiOS firewall-address objects use a targeted inverse instead of this timer: the rollback deletes the exact object the change added, with no reboot.

Rollback may not complete when:

• The change removes the management path and the app can no longer reach the device
• The device is offline, rebooting, failed, or has lost power
• The device did not create, retain, or accept the recovery snapshot
• The platform or current operating mode does not support the required recovery action
• Another administrator or process changed the same configuration after the snapshot
• The recovery command is rejected, only partly completes, or times out

If the device's session has ended, a rollback from the Changes view sends nothing. The app says the device is not connected and offers Connect. The note goes away once the device's session is live again. Reconnect, confirm the device state, then select Roll back again.

A rollback result says two things: whether the configuration was restored, and whether the cleanup was confirmed. If nothing reached the device, the result starts with Nothing was sent, and Roll back stays available. If the configuration was restored but the cleanup was not confirmed, the change shows Change needs attention and names the command to run yourself. On Cisco IOS and IOS XE, the rollback always sets file prompt back to alert and reads it back to confirm, even when the rollback stops after the configuration was restored.

If the app reports that rollback did not complete, stop additional changes. On Cisco IOS, IOS XE, NX-OS, and Arista EOS, the result names the rollback copy the app kept on the device on purpose, and the commands to restore from it by hand. Use the console or out-of-band path, compare the device with the captured before state, and restore service according to your organization's recovery procedure.

7. Make a safe first change#

Choose a small, reversible change with an easy success test. On lab equipment or during the maintenance window:

1. Connect with the least-privilege Credential.
2. Confirm the expected device and current state with read-only commands.
3. Preview the change.
4. Verify that the snapshot, before state, and recovery method are present.
5. Read every changed line and warning.
6. Apply only while independent recovery access is ready.
7. Check the app's verification and perform your own service test.
8. Confirm that the local change record reflects the actual outcome.

Expected Result#

Only an explicitly approved configuration change reaches the selected device. The app captures a redacted before snapshot (retained in the timeline when storage succeeds), prepares the platform's available rollback anchor before sending, reports the apply and verification outcomes, and offers rollback only when that recovery method remains available. The local history and audit trail preserve the recorded intent and outcome for later review.

Troubleshooting#

The preview is refused#

Confirm that the selected platform supports governed writes, Allow configuration changes is turned on under Settings > General, every line belongs to one change, and the proposal contains no unresolved placeholder. A policy refusal cannot be overridden from the approval card.

The before state is missing#

Do not apply the change. Reconnect, confirm that the device account can read the relevant configuration, and preview again. If capture still fails, use your independent backup and recovery process instead of relying on in-app rollback.

Verification is indeterminate#

Check the terminal for a dropped session or device error, reconnect if safe, and verify the affected service manually. Do not treat a missing result as success.

Rollback failed or the device is unreachable#

Stop using the affected management path. Move to console or out-of-band access, follow your recovery procedure, and compare against the captured before state. Do not send another change simply to test whether the connection has recovered. A result that starts with Nothing was sent is not a failed rollback. Nothing reached the device, and Roll back stays available.

Related#

• Resolve
• Investigate
• Credentials
• Troubleshooting
• Security overview