Before a local Copilot session: write down the sandbox boundary

Use this before starting work, not after granting access

Before asking a local coding agent to install dependencies, edit files or open a pull request, write down which files, connections and credentials the task needs—and which it must not reach. The worksheet below turns those requirements into a decision to proceed, narrow the task or stop. It is a planning aid, not a certification that the machine is isolated.

GitHub announced local sandboxing for the Copilot app on 23 September 2026. It is off by default and configured per project for local repository and working tree sessions. App and Copilot CLI sandbox settings are separate; these app settings do not apply to cloud sandbox sessions or sessions on a remote host. A working tree alone does not restrict access elsewhere on the machine. [1] [2]

The distinction to keep throughout: a requirement is what your task must permit or forbid; requested policy is what you configure; effective policy is what applies to that session, including enterprise restrictions. Evidence is what you actually observed. Do not copy the requested column into the effective column just because the app accepted the settings. [2]

What the documented controls do—and do not establish

GitHub recommends starting with the default policy for most projects because it supports ordinary development tasks. This worksheet is most useful when your requirements differ—for example, when no authenticated operation is needed or local-network access must be excluded. Defaults may fit a task, but they are not equivalent to no network or no credentials. [2]

Copy and complete this worksheet

Copy the fields into your project notes. Use one boundary row per sensitive path, connection requirement or credential type. Write “unknown” where evidence is missing. Keep the completed record private if it names sensitive locations; never paste tokens, passwords or secret file contents into it. The labels below are worksheet fields, not app configuration syntax.

• Project and permitted task: ____ | Task owner: ____ | Date/time: ____
• Host OS/version: ____ | Copilot app version: ____ | Session identifier: ____
• Session type: local repository / local working tree / other: ____ | If cloud or remote, stop using this app-local worksheet as enforcement evidence.
• Workspace path: ____ | Current working directory: ____ | Sensitive paths inside or outside them: ____
• Tools/execution paths: shell or other spawned process: ____ | Local MCP/LSP: ____ | In-process web request/remote MCP: ____ | Unknown: ____
• Needed endpoints and purpose: ____ | Internet / loopback / LAN: ____ | Does the requirement demand a specific host or port restriction? ____
• Authenticated HTTPS Git needed? ____ | GitHub CLI authentication needed? ____ | Sensitive files or other credential needs outside these two controls: ____
• Project Sandbox new sessions setting: ____ | Active-session override, if any: ____ | Enterprise-managed restrictions known to apply: ____

• Policy change saved at: ____ | New session or /restart-session completed at: ____ | Session identifier after change: ____
• Verification record: app status/error text ____; first sandboxed-shell startup outcome ____; owner-approved non-sensitive check and execution path ____; expected result ____; observed result ____; evidence location/time ____; not tested ____
• Outside-sandbox decision agreed before work: cancel / escalate to ____; reason ____; no exception authorized by this worksheet.
• Final decision: proceed with the stated task / narrow task and recheck / stop ____ | Unmet or unknown mandatory requirements ____ | Owner, next action and review time ____

Apply the policy to the right session, then separate evidence from assumptions

• For future local sessions, the documented project control is Settings → your project → Sandbox → Sandbox new sessions. It does not change an already-running session. [1] [2]
• For an active local session, /sandbox on creates an immediate, persistent session override without changing the project default. Before a session starts, the same command changes the default inherited by new sessions. Record which context you used. [2]
• After changing file, network or credential settings, use a new session or restart the existing session; the documented command is /restart-session. Editing settings alone does not update the policy of a currently running session. [2]
• Inspect the actual session status and any unsupported-platform or unsupported-policy error. The documented support check happens when the first sandboxed shell starts. Successful startup alone does not prove every boundary you listed. [2]
• For requirements that need runtime evidence, have the responsible owner define non-sensitive, authorized checks for the relevant execution paths. Use disposable test material, not real secrets or production services. Record expected and observed results separately. If no suitable verification exists, mark the requirement unknown and keep sensitive work stopped. This is our proposed verification discipline, not a tested Copilot procedure or a vendor guarantee.

Filled example: a Linux dependency check that should stop

Hypothetical planning example only; none of the following settings or checks was executed. A developer wants a shell-based dependency check in a local working tree at /work/catalog. It needs an internet package registry, must not reach LAN or loopback services, must not read /work/private, and needs neither authenticated Git nor GitHub CLI. The host is Linux; exact OS and app versions would still need recording.

Next action: keep the job stopped and ask the responsible owner for an environment that can establish the required boundary. Alternatively, narrow the job to an offline check using already-approved local inputs, then reassess and verify the revised requirements. Do not turn local-network access on, run outside the sandbox, or substitute an in-process result as proof of the shell’s behavior merely to finish the task.

When to stop rather than weaken the boundary

• The session is cloud-hosted, remote-hosted or using separately configured Copilot CLI: obtain that environment’s own controls and evidence instead of carrying over app-local conclusions. [1] [2]
• A mandatory boundary is unsupported, unmet or unknown—including a Linux spawned-process distinction the docs do not support. Narrow the task or seek an appropriate environment; do not mark the requirement met.
• Settings changed but the relevant session was not restarted, the active override is unclear, or enterprise restrictions prevent the task. Resolve the applicable policy first. [2]
• The app reports Sandbox unavailable or an unsupported policy/platform. GitHub documents fixing the reported problem and using Retry sandbox; disabling the sandbox is not an equivalent fix. [2]
• A tool asks to run outside the sandbox. Cancel while you review the exact operation, why the boundary was hit and who owns the decision. GitHub documents options to cancel, run once outside, or disable sandboxing for the remainder of the session, depending on effective policy; an enterprise owner can prohibit outside execution. Those options are not permission from this worksheet. [2]

A useful completed worksheet can end in “stop.” Proceed only with a clearly bounded task and evidence appropriate to its requirements; keep remaining limits visible. This resource summarizes GitHub’s documented controls and proposes a way to record decisions. It does not demonstrate that data leakage is impossible, that all credentials are isolated, or that a particular host enforces the requested policy.