AI coding agents can read files, execute commands, modify source code, run tests, and interact with development tools. That makes them useful for daily development, but it also means their permissions should be tested before using them on an important codebase.
GitHub Copilot CLI provides local sandboxing to control access to the filesystem, network, credentials, and other system resources. Because sandbox behavior and configuration can change, developers should verify the effective policy instead of assuming that a particular permission is available or blocked.
This article walks through a practical way to test GitHub Copilot sandbox rules before allowing an agent to work on a project.
Why Test Sandbox Rules First?
A sandbox configuration can be too permissive or too restrictive.
A permissive configuration may expose files or resources that the agent does not need. A restrictive configuration can prevent normal development commands from working.
For example, a .NET project may require access to:
src/
tests/
.git/
NuGet packages
.NET SDK
But the same project should not normally require access to unrelated personal documents.
The goal is to find the smallest permission set that allows the development workflow to work.
This follows the principle of least privilege:
Required access
↓
Test the access
↓
Remove unnecessary permissions
↓
Run the complete workflow
Understanding What the Sandbox Controls
Before testing, it helps to separate the different types of access.
Permission Area | What It Controls | Example |
|---|
Filesystem | Files and directories | Read source code |
Write access | Ability to change files | Modify a C# class |
Network | External or local network connections | Download packages |
Git authentication | Authenticated Git operations | Push changes |
GitHub CLI authentication | GitHub CLI operations | Create a pull request |
Toolchain access | Development tools | .NET SDK, Node.js |
Git metadata | Repository operations | git status, git diff
|
A sandbox rule that allows one type of access does not necessarily grant all other permissions.
For example, allowing a project directory to be writable does not automatically mean that every network resource should be available.
Step 1 - Start With a Test Project
Do not test a new sandbox policy directly against a critical production repository.
Create a small project that contains files specifically designed for testing.
For example:
SandboxDemo/
├── src/
│ └── Program.cs
├── tests/
│ └── ProgramTests.cs
├── data/
│ └── test-data.json
└── .git/
A simple .NET project is enough for most filesystem and command tests.
You can create it with:
dotnet new console -n SandboxDemo
cd SandboxDemo
Initialize Git if required:
git init
The test project gives you a controlled environment where you can safely determine what Copilot can read, modify, and execute.
Step 2 - Enable Local Sandboxing
GitHub Copilot CLI supports local sandboxing as an experimental capability.
You can enable the experimental features and then enable the sandbox:
/experimental on
Then:
/sandbox enable
You can also start a session with sandboxing enabled:
copilot --sandbox
The exact availability of these options can depend on the current Copilot CLI version and configuration.
For that reason, check the commands available in your installed version rather than copying an older configuration blindly.
Step 3 - Inspect the Effective Policy
Before testing commands, inspect the policy.
Use:
/sandbox policy
This is one of the most important steps.
Do not assume that the policy matches what you configured manually. The effective policy can include defaults and automatically resolved permissions.
You want to answer questions such as:
What directory is writable?
What directories are readable?
Is .git accessible?
Is network access enabled?
Are Git credentials available?
Are GitHub CLI credentials available?
Can installed development tools be accessed?
Write down the expected behavior before testing.
For example:
Test | Expected Result |
|---|
Read src/Program.cs | Allowed |
Modify src/Program.cs | Allowed |
Read unrelated directory | Restricted |
Run dotnet test | Allowed |
Run git status | Allowed |
Access network | Depends on policy |
Access credentials | Depends on policy |
This gives you something concrete to verify.
Step 4 - Test Read Access
Start with the simplest operation - reading a project file.
For example:
cat src/Program.cs
On Windows PowerShell, you can use:
Get-Content .\src\Program.cs
The command should work if the project directory has the required read permission.
Then test a location that should not be accessible.
For example, do not test against a real secret directory. Instead, create a harmless test directory outside the project:
SandboxOutsideTest/
└── test.txt
Ask the agent to read it.
If the sandbox is configured to deny access, the operation should fail or be blocked.
This is an important test because checking only allowed paths does not tell you whether the restriction is actually working.
Step 5 - Test Write Access
Reading and writing are different permissions.
Create a test file:
src/sandbox-test.txt
Then ask the agent to modify it.
For example:
Add the text "Sandbox write test" to src/sandbox-test.txt.
If the project directory is writable, the operation should succeed.
Now test a directory that should be read-only.
The goal is to verify that an agent cannot simply write anywhere it can read.
This distinction is especially important for repositories containing generated files, configuration files, deployment scripts, and infrastructure definitions.
Step 6 - Test Git Access
Git operations often need access to the .git directory.
Start with:
git status
Then:
git diff
You can also test creating a harmless local commit in your test repository.
For example:
git add .
git commit -m "Sandbox test"
If these commands fail after changing sandbox permissions, check whether .git is still accessible.
A common mistake is to make filesystem permissions so restrictive that the source files remain available but Git metadata is blocked.
The result can be confusing because:
git status
may fail even though the source code itself can still be read.
Step 7 - Test Build and Test Commands
A sandbox should be tested against the actual development workflow.
For a .NET project:
dotnet restore
Then:
dotnet build
And:
dotnet test
These commands can require different resources.
For example, dotnet restore may require network access if packages are not already available locally.
dotnet build needs access to the SDK and project files.
dotnet test needs the test binaries and related build output.
A policy that passes a simple file-read test may still fail when you run the complete build pipeline.
Step 8 - Test Network Permissions
Network access should be tested separately.
Do not use an unknown website or production endpoint as a test.
Instead, use a development dependency or another controlled endpoint appropriate for your environment.
For example, a package restore can provide a practical test:
dotnet restore
If the project already has all packages cached locally, this test may not prove that outbound network access works.
That is why network testing should be designed intentionally.
If your project does not require network access during agent execution, consider restricting it.
If the project requires package installation, API testing, or another network operation, make sure the required access is available without unnecessarily widening the policy.
Step 9 - Test GitHub CLI Authentication
GitHub CLI authentication should be tested independently from filesystem access.
For example:
gh auth status
If GitHub CLI authentication is available to the sandbox, the command can report the authenticated state.
If the project only requires code analysis and local testing, authenticated GitHub CLI access may not be necessary.
This is an important distinction:
Agent needs GitHub repository files
≠
Agent needs GitHub account credentials
Do not grant credentials simply because the project is hosted on GitHub.
Step 10 - Test Failure Conditions
A good sandbox test does not only confirm what works.
It also confirms what is supposed to fail.
For example:
Test | Expected |
|---|
Read project source | Pass |
Modify project source | Pass |
Run tests | Pass |
Run Git status | Pass |
Read protected test directory | Fail |
Write to protected directory | Fail |
Access unnecessary credentials | Fail |
Unapproved network connection | Fail |
Testing failure conditions is critical.
If every operation succeeds, your policy may be broader than necessary.
Testing With a Simple C# Program
You can also create a small program that attempts filesystem access.
For example:
using System;
class Program
{
static void Main()
{
string path = "src/Program.cs";
try
{
string content = File.ReadAllText(path);
Console.WriteLine("File read succeeded.");
Console.WriteLine(content);
}
catch (Exception ex)
{
Console.WriteLine($"File read failed: {ex.Message}");
}
}
}
This gives you a repeatable way to test filesystem behavior.
You can change the path to another controlled test location and verify whether the sandbox allows or denies the operation.
The important part is not the C# code itself. The value comes from using repeatable tests instead of relying on assumptions.
Testing Read-Only Permissions
Read-only access deserves its own test.
Suppose a directory contains configuration templates that Copilot needs to inspect but should not modify.
You can test this with:
using System;
using System.IO;
class Program
{
static void Main()
{
string path = "config/test.txt";
try
{
Console.WriteLine(File.ReadAllText(path));
File.AppendAllText(path, Environment.NewLine + "test");
Console.WriteLine("Write succeeded.");
}
catch (Exception ex)
{
Console.WriteLine($"Operation failed: {ex.Message}");
}
}
}
If the path is read-only under the sandbox policy, reading should work while writing should fail.
This is a much better test than simply asking whether the directory is accessible.
Common Mistakes When Testing Sandbox Rules
Testing Only Successful Operations
A policy is not properly tested if you only check files that should be accessible.
Always include negative tests.
Using Real Secrets
Never place real passwords, API keys, private certificates, or production credentials in a sandbox test.
Use harmless test data.
Testing on a Production Repository
Sandbox testing can involve deliberately failing commands and changing permissions.
Use a dedicated test repository first.
Assuming Read Access Means Write Access
These are separate permissions.
Always test both.
Forgetting Git Metadata
A repository can appear healthy while Git commands fail because .git is inaccessible.
Testing Network Access With Production Services
Use controlled development resources.
The purpose of the test is to verify permission behavior, not to test a production service.
Granting More Permissions When Something Fails
A failed command does not automatically mean that the sandbox needs unrestricted access.
First determine exactly which permission is missing.
Troubleshooting Sandbox Test Failures
git status Fails
Check .git access.
The Git repository metadata must be available to the command.
dotnet restore Fails
Check whether network access is available and whether the required .NET SDK and package directories can be accessed.
Build Works but Tests Fail
Check access to the test project, build output, temporary directories, and test dependencies.
A File Is Readable but Cannot Be Modified
This usually indicates a read-only permission.
That may be expected behavior.
A Command Works Without Sandboxing but Fails With It
Compare:
/sandbox policy
with the resources required by that command.
Do not immediately disable the sandbox. Identify the missing permission first.
Best Practices for a Safe Test Process
Start With Minimum Permissions
Begin with the project directory and only the access required to build and test.
Use a Dedicated Test Repository
This prevents accidental modification of important source code.
Test the Complete Developer Workflow
A useful test should include:
Read
Write
Build
Test
Git
Package restore
Network
Authentication
Not every project needs all of these.
Record Expected Results
Maintain a simple checklist for each project.
For example:
[PASS] Read source
[PASS] Modify source
[PASS] Build
[PASS] Run tests
[PASS] Git status
[BLOCKED] Read protected directory
[BLOCKED] Write protected directory
This makes policy changes easier to validate later.
Re-Test After Configuration Changes
A sandbox policy can affect development commands in unexpected ways.
Whenever permissions change, run the test suite again.
Advantages of Testing Sandbox Rules
Reduces surprises: Developers know what the agent can and cannot do before using it on important code.
Improves security: Unnecessary permissions can be identified and removed.
Makes troubleshooting easier: Permission failures can be reproduced in a controlled environment.
Supports least privilege: The project can receive only the resources it actually needs.
Creates repeatable validation: The same tests can be run after future configuration changes.
Disadvantages and Limitations
Requires additional setup: A proper test environment takes time to create.
Policies can be complex: Filesystem, network, Git, and authentication permissions are separate concerns.
Tool requirements vary: A .NET project may need different access from a Node.js or Python project.
Sandbox behavior can evolve: Experimental functionality can change between versions.
A successful sandbox test is not a complete security audit: Other application, operating-system, dependency, and credential risks still need to be addressed.
A Practical Sandbox Test Checklist
Before allowing an AI agent to work on an important project, verify:
[ ] Sandbox is enabled
[ ] Effective policy has been reviewed
[ ] Project files can be read
[ ] Required files can be modified
[ ] Unrelated directories are restricted
[ ] .git works correctly
[ ] Build works
[ ] Tests work
[ ] Required package restores work
[ ] Network permissions are understood
[ ] Git authentication is required only when necessary
[ ] GitHub CLI authentication is required only when necessary
[ ] Negative permission tests fail as expected
[ ] No real secrets were used during testing
Conclusion
Testing GitHub Copilot sandbox rules before using them on a real project is a practical security step.
The objective is not to block every operation. A development agent needs enough access to read code, make changes, build the application, run tests, and perform other tasks that are part of the workflow.
The important part is understanding exactly what access is required.
Start with a dedicated test repository, inspect the effective policy, test both successful and blocked operations, and then run the complete development workflow. Pay particular attention to filesystem permissions, .git access, network connectivity, package restoration, and authentication.
Most importantly, do not treat a sandbox as a substitute for secure development practices. It is one layer of control that can help reduce unnecessary access while allowing an AI coding agent to remain useful.
Join the conversation! Your thoughts help the community grow.