#Where commands run

Every Shell session runs somewhere you choose — directly on your own machine, or in a secure, isolated environment kept separate from your system.

#Overview

The Shell can run a session in one of two places: locally on your own machine, where it works directly with your real files and tools, or in a secure, isolated environment kept separate from your system, where work stays sandboxed and contained. You decide which one fits the task.

This choice is about reach, not power. The local option is for working hands-on with your own machine — your projects, your files, the tools you already have installed. The isolated option is for work you want kept apart from your system, so nothing it does can touch anything outside its boundary. Both run the same way, stream output live, and respect the permission level you set; they differ only in where the work lands.

#What you can do

You choose where a session's work runs, and the two options serve different needs:

  • Run locally on your own machine. The session works directly with your real environment — your files, your folders, and the tools installed on your machine. This is for hands-on work where the point is to affect your own system: building in a real project, running your own tools, operating on files you keep.
  • Run in a secure, isolated environment. The session works in a space kept separate from your system. Nothing it does reaches your machine or your files unless you bring the result back. This is for work you want sandboxed — trying something you are unsure about, running something you do not fully trust, or keeping an experiment cleanly apart from everything else.

In both cases you keep the rest of the Shell's control:

  • The session streams its output live, line by line, as commands run.
  • A long job keeps running in the background, and you are told when it finishes.
  • The session is confined to a workspace, so its actions stay where you intend.
  • It runs at the permission level you set, and stopping always works immediately.
  • It keeps a durable receipt of what it did, so nothing is lost if you step away.

#How to use it

  1. Decide what the work is for. If you want the session to act on your own machine and files, choose local. If you want the work kept apart from your system, choose the isolated environment.
  2. Choose where the session runs when you start it. The choice belongs to the session: everything you do in that session runs in the place you picked.
  3. Set a permission level that fits. Where a session runs and how much freedom it has are separate choices. For unfamiliar work, start cautious — Look only or Plan first — whichever place you run it.
  4. Watch the first run. The output streams live wherever the session runs, so you can confirm it is doing what you expect before giving it more freedom.
  5. Bring results back when you need them. Anything a session produces is saved as an artifact you can find, reopen, and reuse — so work done in an isolated environment is still yours to keep.
Tip

When you are unsure whether something is safe to run, start it in the isolated environment. It gives you the full Shell experience while keeping your own machine untouched, and you can move to a local session once you trust the work.

Note

Where a session runs is a property of the session itself, not of each command. Pick the place when you start the session, and run as many commands inside it as you like.

#Examples

text
Run this in a sandbox first — I don't fully trust it yet.

You see a session start in the secure, isolated environment, with its output streaming live. Whatever the command does stays inside that environment, separate from your own machine, and you can review exactly what happened before deciding whether to run it for real.

text
Build the project in my local folder and run the tests.

You see a local session work directly in your own project, with the build and test output streaming back live, line by line. The results land in your real environment, and the finished work is saved as an artifact you can reopen.

text
Try this experiment somewhere it can't touch my files.

You see a session begin in the isolated environment, kept apart from your system. It runs the experiment, streams the output, and keeps a durable receipt — and nothing it did reaches your machine or your files.

#Tips

  • Match the place to the intent: choose local when the goal is to affect your own machine and files, and the isolated environment when the goal is to keep the work contained.
  • Use the isolated environment as your default for anything unfamiliar or untrusted; it gives you the full Shell with none of the exposure.
  • Remember that where a session runs is independent of its permission level — pair an isolated environment with a cautious level when you are exploring something new.
  • Results from either place are saved as artifacts, so running in isolation never means losing the work — bring it back when you are ready.