Use terminals

What CoCalc terminals are for

CoCalc terminals are shell sessions inside a project. Hosted CoCalc projects use Linux; local CoCalc installations use the host operating system's shell, including PowerShell on Windows. The terminal UI runs in the browser, while the shell process runs in the project backend. Commands can continue through a browser disconnect while that backend runtime remains running.

Use terminals to install packages, run scripts, inspect files, start services, use Git, manage virtual environments, and work with command-line tools that are part of the project environment.

Open and organize terminals

Open a terminal from New on the project activity bar or in Files, or by opening a file ending in .term. For the short action flow, see Open a terminal.

Terminal files are path-based. A terminal at analysis/run.term starts in the analysis/ directory and gives the session a stable project-file anchor. Create separate terminal files for separate tasks when that makes the workspace easier to understand.

Open project files from the terminal

Use the open command to open files and directories in CoCalc from the shell, similar to xdg-open on Linux or open on macOS:

open path/to/file.ipynb path/to/script.py path/to/folder

This is often faster than switching to Files when you are already working in a terminal. Paths are interpreted relative to the terminal's current directory.

Persistent work

Collaborators can reconnect to a terminal while its project runtime is still running. A browser-idle policy can stop the project even while a command is running. Project stops, restarts, and failures also end running processes.

Tools such as tmux help with shell reconnection, but they do not keep a project runtime alive through a stop or restart. Use log files, checkpoints, and scripts so progress is visible and work can resume.

Collaboration and safety

Terminals are collaborative. People with access to the running project can see terminal content and may be able to interact with the shell. Avoid pasting secrets into commands, prompts, logs, or shell history. On hosted CoCalc AI, use project secrets for credentials consumed by project code; find Project secrets in the site's Docs index. Local CoCalc Plus uses the credentials you configure in your local environment.

Agents and automation

Agents should prefer typed CoCalc terminal or browser-session APIs when they need to inspect or drive a live terminal. Use the terminal for real shell work, but avoid relying on screenshot-only automation when a CLI or project API can perform the same operation directly.

Troubleshooting

If a terminal seems unresponsive, check whether the project is running and whether a command is still active. Use Ctrl-C for a foreground command, open a new terminal for independent diagnosis, and inspect project memory if commands are being killed.