Set up and use nuLAB Gateway

What Gateway does

nuLAB Gateway runs on your computer so local tools such as Terminal, PuTTY or SecureCRT can reach supported simulated devices in your active nuLAB lab. Start with the SSH walkthrough below: connect to one router, make a small change, save it, and confirm it in the browser.

The Help page is public. Using Gateway requires a nuLAB account, access to the lab, and permission to configure networking on your computer. The current downloads include their runtime; a separate .NET SDK installation is not part of these steps.

Watch the paired-Mac SSH demonstration

The video starts with installation and pairing already complete. This guide includes those first-time steps and covers Gateway 1.1.4.

Before you start

• Use a computer on which you are allowed to install software and approve administrator access. Ask your IT administrator if it is managed.
• Have a nuLAB account and enough device allowance for the lab you will open.
• Use the same nuLAB account when opening the lab and authorizing Gateway.
• Keep internet access to https://portal.nulab.ai available. Your SSH client connects to a local lab address, while Gateway still needs the Portal.
• Choose lab IP addresses that do not overlap your home, office, VPN or other locally running lab. This guide uses the documentation address 192.0.2.10.
• Prepare a terminal or SSH client. Use the native build for your operating system and processor.

1. Create and verify your nuLAB account

1. Open https://nulab.ai/sign-up. If you already have an account, sign in instead of registering again.
2. Enter your name, email and a password that meets the displayed requirements. Complete the verification challenge and submit the form. If you arrived through a Training Platform invitation, keep that invitation flow and use the invited email.
3. Open the verification email and follow its activation link. Check spam/junk if it does not arrive; use the recovery or resend option offered by the site rather than repeatedly creating accounts.
4. Open https://portal.nulab.ai and sign in. Complete MFA if requested. Confirm that you can reach your Dashboard or My Labs.
5. If sign-in says the account already exists, use Sign in or Forgot password. Website registration, email activation and a signed-in Portal session must be completed before approving Gateway.

Create a nuLAB account (opens in a new tab)

Open the Portal (opens in a new tab)

2. Find the correct download

1. In the signed-in Portal, open Settings, then Downloads. This is also where Gateway token status and its expiry are shown.
2. Choose the build for the operating system and processor of the computer where your terminal client will run.
3. Download from the Portal. On macOS, open the .pkg with Installer and approve the normal system installation prompt. Windows and Linux currently provide executables rather than an automatic service installer.

On a Mac, About This Mac identifies the chip or Intel processor. Native Windows ARM64 and Linux ARM64 builds are not included in the current download set. Use a currently supported operating system; for the bundled runtime, Microsoft currently lists macOS 14, 15 and 26.

Microsoft: supported macOS versions (opens in a new tab)

3A. First-time setup on macOS

1. Finish the correct .pkg installation. Open Terminal. The current package installs a command-line program; a successful installer does not mean Gateway is paired or its background service is enabled.
2. Check the command. If your shell cannot find it, use the full installed path shown below.
3. Run browser pairing as your normal logged-in Mac user. Follow the authorization steps in the next section and return to Terminal when it reports that login succeeded.
4. Approve the one-time service setup with the protected helper command. Enter your Mac administrator password into Terminal when sudo requests it. It is normal for no characters or bullets to appear while typing. This password stays in the local system prompt.
5. Run the service-status command. Then open a lab and complete the external connection test below; a running process alone does not prove the account and device are reachable.

nulab-gateway --help
# If the command is not found:
/usr/local/bin/nulab-gateway --help

nulab-gateway --login --server https://portal.nulab.ai

sudo /Library/PrivilegedHelperTools/ai.nulab.gateway --setup-service --server https://portal.nulab.ai

nulab-gateway --service-status

The expected setup result says that the background service was installed. Once enabled, it starts through macOS and follows your active lab; you do not need to keep a Gateway Terminal window open or approve administrator access every day. Avoid starting a second foreground copy while the service is running.

If you want to preview setup first, add --dry-run to the setup command. A preview makes no installation changes and still performs its checks.

3B. First-time setup on Linux

These commands describe the x64 executable and a systemd-based Linux system. Use your administrator for a different init system or locked-down host. Do not run the macOS package on Linux.

1. Download the Linux executable from Portal Settings → Downloads. In the example it is in ~/Downloads and named nuLAB.Gateway; adjust the source path if your browser used another name.
2. Install it at the protected location below. This intentionally requires administrator approval. Existing writable or incompatible destination directories need administrator review.
3. Run --help, then browser pairing as your ordinary user. If this computer has no usable local browser, use the hidden token method below.
4. Approve one-time service setup with sudo from that same paired ordinary account.
5. Check status, open your lab, and perform the SSH walkthrough. The service uses its own protected pairing copy; changing an ordinary user file later does not update that installed copy.

sudo install -o root -g root -m 755 "$HOME/Downloads/nuLAB.Gateway" /usr/local/bin/nulab-gateway
nulab-gateway --help

nulab-gateway --login --server https://portal.nulab.ai
sudo /usr/local/bin/nulab-gateway --setup-service --server https://portal.nulab.ai
nulab-gateway --service-status

Keep the default systemd service rather than starting another worker for daily use. Setup must be run through sudo by the paired account so it can identify the correct ordinary user. A root login shell is not a substitute for that step.

3C. First-time setup on Windows

1. Download the Windows x64 executable from Portal Settings → Downloads. Keep it in a folder you control and note its exact path. The commands below assume C:\Users\YOUR_NAME\Downloads\nuLAB.Gateway.exe; change the path to yours.
2. Check whether Microsoft KM-TEST Loopback Adapter is already installed in Device Manager under Network adapters. If it is present, do not add another just for this guide.
3. If it is missing, ask your administrator to add it using the Add Hardware Wizard: choose manual installation, Network adapters, manufacturer Microsoft, then Microsoft KM-TEST Loopback Adapter. Windows wording varies; contact IT if that wizard or option is unavailable. The Gateway download does not install it for you.
4. Open PowerShell with Run as administrator. Confirm which Windows account this uses. Pair and run Gateway as that same account; entering a different administrator account uses that other account’s credential store.
5. Run --help, then --login and complete the local browser authorization. After pairing exits successfully, run the executable again without --login and leave that window open.
6. Open your lab in the Portal using the same nuLAB account, then connect with your SSH client. Ctrl+C in the Gateway PowerShell window stops this foreground worker.

& "C:\Users\YOUR_NAME\Downloads\nuLAB.Gateway.exe" --help
& "C:\Users\YOUR_NAME\Downloads\nuLAB.Gateway.exe" --login --server https://portal.nulab.ai
& "C:\Users\YOUR_NAME\Downloads\nuLAB.Gateway.exe" --server https://portal.nulab.ai

Microsoft: find the KM-TEST Loopback Adapter (opens in a new tab)

For an unattended Windows service, use your administrator. Its chosen service identity must be able to read only its intended protected credential store and write its log directory. Pairing in your normal user account does not automatically authorize LocalSystem. There is no published automatic setup script in this release; do not copy an unreviewed service command with a token embedded in it.

4. Complete browser authorization

1. Start --login in a terminal on the computer where Gateway will run. Keep that terminal open while the browser step completes.
2. Gateway opens an authorization page. If it cannot open your browser, use the fresh link printed by that running command on the same computer. Keep the link private.
3. Sign into the nuLAB account that will open the lab, complete MFA if asked, and read the account shown on Authorize nuLAB Gateway.
4. Choose Authorize gateway only if you just started this login yourself and the displayed account is correct. Cancel if it is the wrong account or an unexpected request.
5. Wait for Authentication successful in the browser, then return to Terminal. The final success message says Logged in and Credentials saved after verification. The --login command then exits; that is expected.
6. Continue with your platform’s service setup or foreground-run step. Pairing alone does not start the daily Gateway worker.

If authorization times out, start a fresh --login attempt. A browser on a remote computer cannot complete the local callback for a headless machine; use the token method below instead.

Alternative: pair with a hidden token prompt

Use this when a local browser cannot finish authorization. It still requires an account and a valid Gateway token.

1. On a trusted browser, sign into the same account and open Portal Settings → Downloads.
2. Review the Gateway token status. Choose Generate or Regenerate only when you intend to replace the existing token; the full new token is revealed once. Copy it securely while the reveal is available. A masked saved token is not the full value.
3. Run the appropriate command below on the Gateway computer. Paste only the token into its hidden prompt and press Enter. It is normal not to see the characters.
4. Wait for the accepted-token and credentials-saved result, then continue platform service setup or foreground startup. Rejected input is not a successful pairing. Keep tokens out of screenshots, chat, shell command arguments and source files.

nulab-gateway --login-token --server https://portal.nulab.ai

& "C:\Users\YOUR_NAME\Downloads\nuLAB.Gateway.exe" --login-token --server https://portal.nulab.ai

For several authorized computers, distribute the same current token through a secure channel and use --login-token. Repeating browser authorization on each computer would replace the token again. Never use a nuLAB website password as the Gateway token.

5. Device compatibility and SSH setup

1. In the Portal, open My Labs using the same account that authorized Gateway. Open an existing lab, or choose Create Lab, enter a name such as Gateway practice, then choose Create Lab to enter the editor.
2. For a new empty lab, use the Add device controls to open the selector. Choose Router, Cisco, IOS-XE and model ISR4451; name it R1, keep one device, choose an available OS version, and confirm the addition. This single-router Loopback0 example does not require another device or cable.
3. Select R1 in the Devices list and choose Terminal. Make sure the device is powered on, and wait for its CLI prompt. Configure the address and SSH login in this browser terminal before using the external client. Gateway does not create router usernames, enable SSH or grant device privileges for you.
4. For a small practice lab, use the IOS-XE example below on an appropriate Cisco ISR4451 profile. It creates a Loopback0 address and a dedicated lab login. Replace REPLACE_WITH_YOUR_LAB_PASSWORD before entering the commands. Other vendors use their own syntax.
5. Check the interface and its address from the browser terminal. Keep this lab active while making the first external connection.

enable
configure terminal
ip domain-name lab.example
username labuser privilege 15 secret REPLACE_WITH_YOUR_LAB_PASSWORD
crypto key generate rsa modulus 2048
ip ssh version 2
interface Loopback0
ip address 192.0.2.10 255.255.255.255
description GATEWAY-PRACTICE
exit
line vty 0 4
login local
transport input ssh
end
write memory

show ip interface brief
show running-config interface Loopback0

You should see Loopback0 with 192.0.2.10 and an operational interface state. Use your actual address in the external client. Avoid reusing an address already assigned to a different active lab interface or a host/VPN interface. The example is a simulation exercise, not a configuration to paste into production equipment.

6. Connect from your local terminal or SSH client

1. Confirm Gateway is running and the prepared lab is active. Use your platform’s status check or foreground window.
2. On the same computer, open Terminal, PowerShell, PuTTY or SecureCRT and create an SSH connection to the device address.
3. For a new host-key prompt, confirm that the address and key are the ones you expect before accepting. If the key unexpectedly changed, stop and investigate rather than disabling host-key checking.
4. Enter the simulated device’s username and password. In this example the username is labuser, not your nuLAB email. The password is the lab password you set on the router.
5. Confirm the device prompt, then inspect the interface before changing configuration.

ssh -l labuser 192.0.2.10

If the ssh command is unavailable, use an installed SSH client such as PuTTY or SecureCRT with the connection fields above, or ask your administrator to provide a supported SSH client.

7. Save a change and verify it in the browser

1. In the external device session, inspect the current interface. Make the small description change below, then save it.
2. Return to the same router’s browser terminal. Read both the running interface configuration and the saved startup configuration.
3. Confirm that GATEWAY-DEMO appears in both places. That checks the actual device workflow; the service process being running would not prove this result.

enable
show running-config interface Loopback0
configure terminal
interface Loopback0
description GATEWAY-DEMO
end
write memory

show running-config interface Loopback0
show startup-config | include GATEWAY-DEMO

To end the connection, use your SSH client’s disconnect action and confirm that you return to your computer’s shell. For OpenSSH with its default escape settings, press Enter, then type ~. to disconnect. A device CLI exit command can merely change configuration mode; check that the network session actually ended.

Daily use after first-time setup

1. Sign into the Portal using the paired nuLAB account and open the lab you intend to use.
2. On macOS/Linux, let the installed background service run. On Windows, start your configured foreground worker or administrator-managed service.
3. Check the device address and device access configuration, then open the external connection.
4. Save the device configuration when needed and verify the result. Disconnect the client when finished.

You do not need to register, authorize Gateway or approve service setup again each day. A closed browser window does not close the active lab or guarantee that its Gateway access ends. If you want Gateway access stopped, stop the Gateway worker/service deliberately. Do not delete a lab merely to disconnect an SSH client.

If you need a persistent stop of an automatically supervised Gateway service, use the documented service removal procedure below. Keep the original pairing if you intend to enable the service again. A foreground worker stops with Ctrl+C.

Client and protocol compatibility

Available behavior depends on the selected simulated device and the feature it implements. The walkthrough and video above verify SSH on the shown macOS/IOS-XE setup; they do not establish that every protocol, vendor or operating system behaves identically.

Troubleshooting in order

Start with the first failed step. Avoid changing the router, account and host networking all at once.

Find the right logs and ask for help

An explicit --log-dir overrides the default. For a foreground troubleshooting run, --verbose adds connection information to the console. Do not start another worker over an already running service just to collect a log.

• Include your OS/processor, the downloaded Gateway release, whether it is a service or foreground run, and the approximate failure time.
• Describe the last successful step and the first failed one. Share the relevant error lines and service-status output.
• Redact tokens, full authorization/callback links, private credential-file contents, device passwords and unrelated personal data. Do not send your administrator password.

Contact nuLAB support

Changing accounts, renewing or revoking access

1. Treat token renewal as a deliberate change. Settings → Downloads shows its status and expiry; browser authorization, regeneration or revocation can invalidate an existing pairing.
2. For an installed macOS/Linux service, remove that Gateway-owned service with the platform command below before changing the ordinary user pairing. This retains the ordinary pairing until you replace or log it out.
3. As the normal user, run --login for a fresh browser authorization, or --login-token with the current valid token. Confirm the intended account and successful verification.
4. Run --setup-service again from that paired ordinary account using sudo, then check service status and the actual external device connection.
5. Update every other affected installation with the same current token if they need to keep access. Repeated browser authorization on each machine will keep replacing the token.

If a token may be exposed, use Revoke Gateway token in Portal Settings → Downloads and review the affected computers. --logout only removes that local user’s stored pairing; it does not revoke the account token or erase a running service’s protected copy.

Updating Gateway

1. Check Settings → Downloads for the current published release and download the correct architecture. Keep your existing pairing if it is still valid.
2. Install the new Mac package, or have the administrator replace the protected Linux/Windows executable. Do not overwrite files with an unrelated download.
3. Restart the existing service deliberately so it uses the new executable. If setup reports an earlier owned service definition that needs migration, follow its explicit remove/setup instructions instead of forcing replacement.
4. Recheck service status, open a lab and test an external connection. New package installation alone does not prove that an already running worker has restarted.

sudo launchctl kickstart -k system/ai.nulab.gateway

sudo systemctl restart nulab-gateway.service

For a Windows foreground run, stop it with Ctrl+C before replacing the executable, then start it again. Have the administrator handle a configured Windows service and retain its protected credentials and identity.

Stop the service or remove local pairing

Disconnect client sessions first. The following administrator commands remove only a service installed by Gateway’s setup command after verifying its ownership. Add --dry-run to preview. Unknown or modified installations are refused for manual review.

sudo /Library/PrivilegedHelperTools/ai.nulab.gateway --remove-service --server https://portal.nulab.ai

sudo /usr/local/bin/nulab-gateway --remove-service --server https://portal.nulab.ai

Successful service removal stops the worker and removes its owned service definition and protected service pairing. It retains the ordinary user pairing, installed program and logs. Removing the local account pairing afterwards is a separate optional step:

nulab-gateway --logout

& "C:\Users\YOUR_NAME\Downloads\nuLAB.Gateway.exe" --logout

For a Windows foreground run, Ctrl+C stops the worker. A Windows service requires administrator-managed stopping and removal; its protected credential copy is not removed by a different user’s --logout. For complete program removal, have the administrator review the installed files after the service is stopped. Do not delete or change unrelated network adapters, host services or other users’ credentials.