CROSH Commands for Developers: Debugging, Diagnostics, and Development Workflows on ChromeOS

Learn how to use CROSH to debug Crostini crashes, fix port forwarding, run SSH, and profile memory on ChromeOS. A practical developer-focused command reference.

Ekin Yalgın

April 21, 2026·6 min read

CROSH Commands for Developers: Debugging, Diagnostics, and Development Workflows on ChromeOS

The Error starting penguin container message or a silently failing localhost port forward can bring your ChromeOS development workflow to a complete halt. Relying solely on the Linux terminal is a critical mistake when the ChromeOS Developer Shell provides low-level diagnostics and virtualization controls that Crostini cannot reach.

Access Shortcut: Press Ctrl + Alt + T in any Chrome window.
Developer Mode Requirement: Not required for standard commands. Full bash shell access requires Developer Mode.
Primary Subsystems Administered: Termina VM, Crostini containers, Network routing.
Environment: Native Chrome browser tab process.

CROSH vs. Linux Terminal (Crostini): When to Use Which?

The ChromeOS ecosystem operates on multiple layers, making it confusing to know where to execute specific commands. CROSH is the host layer command line interface. The Linux terminal you launch from your app drawer operates entirely inside an isolated container called Penguin.

Use the Linux terminal for installing packages, running Node.js scripts, or executing Git commands. Open CROSH when the container itself fails to launch, when network packets drop before reaching your local server, or when you need to allocate physical disk space. The host shell has ultimate authority over the virtual machines. It manages hardware states while Crostini manages your software stack.

Managing Crostini Workflows with VMC Commands

Virtual Machine Control commands give you direct manipulation over the Termina environment. This is your primary toolkit for handling container crashes without resorting to a full system reboot.

Restarting and Debugging Crashed Linux Containers

Linux containers sometimes freeze during heavy build processes or package updates. Rebooting the entire Chromebook wastes time and disrupts your browser workflow. You can restart the virtual machine directly from the host shell.

Open a new shell tab and type vmc stop termina to forcefully kill the virtual machine process. Wait a few seconds for the host to clear the memory allocation. Then run vmc start termina to initialize a clean boot sequence for the container. This precise restart mechanism saves minutes of downtime during active development.

Managing Storage and Disk Images for VMs

Disk space runs out quickly when managing multiple Docker images, large Node modules, or conda environments with heavy scientific packages. ChromeOS dynamically allocates space, but manual intervention is sometimes necessary for cleanup or backups.

Use the vmc export termina [file_name.tgz] command to create a complete backup of your development environment directly to your ChromeOS Downloads folder. If your container becomes corrupted beyond repair, vmc destroy termina wipes the virtual machine entirely. This provides a clean slate for a fresh Linux installation without factory resetting the hardware.

Network Diagnostics for Local Dev Servers

Testing web applications locally on ChromeOS introduces complex routing challenges. Traffic must cross the bridge between the Chrome browser host and the Linux container guest.

Troubleshooting Localhost and Port Forwarding Issues

A React or Express server running on localhost:3000 inside Linux should automatically forward to the Chrome browser. When this bridge fails, the browser returns a connection refused error.

Launch the shell and execute network_diag to generate a text log of all active routing tables. In the output, look for lines marked FAIL or ERR under the DNS and gateway sections, which point directly to where the forwarding chain breaks. If the port forwarding mechanism is stuck after a container restart, run vmc stop termina && vmc start termina from CROSH to reset the bridge, then relaunch your dev server.

Advanced Packet Tracing and Connection Drops

API requests to external services sometimes fail due to restrictive corporate networks or VPN conflicts. You need to know exactly where the packet drops.

Run tracepath [domain] to map the exact hop sequence from your machine to the remote server. Unlike standard diagnostic tools, this command identifies MTU bottlenecks along the path. For continuous monitoring while adjusting firewall rules, use the classic ping command to watch packet return times in real time.

Secure SSH Workflows Directly from ChromeOS

Developers often install heavy third-party Chrome extensions or Android apps just to manage remote servers. This adds unnecessary security risks and bloats the system. ChromeOS features a native, highly secure SSH client built directly into the host shell.

Type ssh [username]@[hostname] to initiate a secure connection. This native client supports standard authentication methods and key management. If you need to clear outdated keys after a server rebuild, the ssh_forget_host command instantly removes specific cached host fingerprints. The environment is restrictive but highly efficient.

System Profiling: Memory, Battery, and Process Diagnostics

ChromeOS task manager lacks the granular detail required to identify background memory hogs affecting your virtual machines. CROSH gives you host-level visibility that the built-in tools skip entirely.

Identifying Memory Leaks in ChromeOS (top, memory_test)

Heavy IDEs running inside Linux compete for resources with active browser tabs. You need precise data to balance the load.

Execute the top command to view a live, constantly updating list of all processes consuming CPU and RAM at the host level. It reveals background Chrome extensions dragging down system performance. If you suspect hardware degradation or severe memory corruption during heavy build workloads, the memory_test command performs a rigorous read and write validation on your physical RAM modules.

Battery Diagnostics for Long Build Sessions

Build processes drain battery faster than browsing. ChromeOS task manager gives no detail on power draw sources.

Run battery_test 60 to measure real-time charge rate and discharge efficiency over 60 seconds. A result showing high power drain while the Linux container is idle points to a rogue process inside Termina. The battery_firmware info command reveals the full battery hardware status including cycle count and design capacity, which helps distinguish software power leaks from hardware degradation.

Developer Quick Reference: CROSH Commands by Use Case

Task	Command	Notes
Restart Linux container	`vmc stop termina && vmc start termina`	No full reboot needed
Backup dev environment	`vmc export termina backup.tgz`	Exports to Downloads
Wipe and reset Linux	`vmc destroy termina`	Cannot be undone
Check all active routes	`network_diag`	Highlights blocked ports
Trace packet path	`tracepath [domain]`	Shows MTU bottlenecks
Live ping test	`ping [host]`	Monitors connection stability
SSH into remote server	`ssh [user]@[host]`	No extension needed
Clear cached host key	`ssh_forget_host`	Use after server rebuild
Watch all host processes	`top`	Shows Chrome + Linux resource use
Test RAM stability	`memory_test`	Good after kernel updates
Measure battery draw	`battery_test [seconds]`	Detects Termina power drain
Check battery hardware	`battery_firmware info`	Shows cycle count and capacity

When you hit the "Error starting penguin container" message, vmc stop termina && vmc start termina is the first thing to run, not a full reboot. If the container starts but your dev server still can't be reached, that's a host-layer routing issue, and network_diag tells you exactly where. The SSH client handles remote connections without any extension, keeping the security surface small.

FAQ

Frequently Asked Questions

Press Ctrl + Alt + T in any Chrome browser window. A new tab opens with the CROSH shell prompt. No Developer Mode is required for most commands.

CROSH runs at the ChromeOS host layer and controls hardware, virtual machines, and network routing. The Linux terminal (Crostini) runs inside an isolated container called Penguin. Use the Linux terminal for package management and coding; use CROSH when the container itself crashes or network routing breaks.

Open CROSH and run vmc stop termina, wait a few seconds, then run vmc start termina. This restarts only the Termina virtual machine without touching your browser session or other apps.

Run network_diag in CROSH and look for FAIL or ERR entries under the DNS and gateway sections. If the bridge is stuck after a container restart, running vmc stop termina followed by vmc start termina resets the forwarding layer. Then relaunch your dev server.

Yes. Type ssh username@hostname directly in CROSH. The native SSH client supports standard key-based authentication. To remove an outdated host key after a server rebuild, use ssh_forget_host.

Run battery_test 60 to measure discharge rate over 60 seconds. For full hardware details including cycle count and design capacity, run battery_firmware info.

Use vmc export termina backup.tgz in CROSH. This creates a compressed archive of your entire Termina VM in your Downloads folder, including installed packages and configurations.

No. Standard CROSH commands including network_diag, vmc, ping, ssh, battery_test, and memory_test all work without Developer Mode. Developer Mode is only needed if you want full bash shell access at the system level.

Published in

Operating Systems