Pi Agent Sandbox Tutorial: How to Choose Docker, OpenShell and Gondolin Permission Isolation

This tutorial by Pi Agent only deals with the specific task in the title. Pi inherits the file, process, network, and credential permissions of the startup user by default; Docker, Gondolin, and OpenShell address different trust boundaries and cannot be selected solely based on installation difficulty.

All the following operations are first placed in the test repository, test account or service that listens only on the loopback interface. The domain name, username, path and key in the command are placeholders and need to be replaced before execution.

First draw the boundaries that Pi can access by default

This section solves the problem of “first drawing the boundaries that Pi can access by default”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.

For Pi Agent, the basis for judgment is: Pi inherits the file, process, network and credential permissions of the startup user by default; Docker, Gondolin and OpenShell solve different trust boundaries and cannot be selected solely based on installation difficulty. Don’t accidentally open more permissions at this stage.

1
2
3

whoami
Get-Location
Get-ChildItem Env: | Select-String -Pattern 'KEY|TOKEN'

Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.

Difference table of three isolation schemes

Process in the following order:

1. Read the actual version and current configuration.
2. Change only one setting relevant to this section.
3. Run a read-only or revocable request.
4. Check logs, exit codes, and final files.
5. Revert the previous modification if it fails.

1

docker version

The completion criterion here is not that the interface appears, but that the “difference table of the three isolation schemes” has reproducible results.

Docker is suitable for one-time warehouse tasks

1

docker run --rm -it -v ${PWD}:/workspace -w /workspace node:22 bash

Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.

How to separate read-only mounts and writable mounts

Prepare a success sample and a failure sample around “How to separate read-only mounts and writable mounts”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.

1

docker run --rm -it -v ${PWD}:/workspace:ro -w /workspace node:22 bash

It is recommended to record the following four items:

• Pre-execution version or Git commit.
• Actual input, no secret value recorded.
• Observable output, status code or diff.
• Recovery actions and review results after recovery.

If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.

Risks of injecting Provider keys into containers

This section addresses the “Risk of Injecting Provider Keys into Containers”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.

For Pi Agent, the basis for judgment is: Pi inherits the file, process, network and credential permissions of the startup user by default; Docker, Gondolin and OpenShell solve different trust boundaries and cannot be selected solely based on installation difficulty. Don’t accidentally open more permissions at this stage.

1

docker run --rm -it --env-file .env.agent node:22 bash

Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.

Why does Gondolin retain host authentication?

Process in the following order:

1. Read the actual version and current configuration.
2. Change only one setting relevant to this section.
3. Run a read-only or revocable request.
4. Check logs, exit codes, and final files.
5. Revert the previous modification if it fails.

1

pi

The completion criterion here is not that the interface appears, but that “Why does Gondolin retain host certification” have repeatable results.

OpenShell is suitable for policy controlled execution

1

pi

Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.

Verify that unauthorized access is indeed rejected

Prepare a success sample and a failure sample around “verify that the unauthorized read is indeed rejected”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.

1

docker run --rm -v ${PWD}:/workspace:ro node:22 sh -lc 'touch /workspace/should-fail'

It is recommended to record the following four items:

• Pre-execution version or Git commit.
• Actual input, no secret value recorded.
• Observable output, status code or diff.
• Recovery actions and review results after recovery.

If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.

Restrict outbound networks instead of just closing ports

This section addresses “restricting outbound networks rather than just closing ports.” First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.

For Pi Agent, the basis for judgment is: Pi inherits the file, process, network and credential permissions of the startup user by default; Docker, Gondolin and OpenShell solve different trust boundaries and cannot be selected solely based on installation difficulty. Don’t accidentally open more permissions at this stage.

1

docker network ls

Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.

Git identity and submission ownership within the container

Process in the following order:

1. Read the actual version and current configuration.
2. Change only one setting relevant to this section.
3. Run a read-only or revocable request.
4. Check logs, exit codes, and final files.
5. Revert the previous modification if it fails.

1
2

git config user.name
git config user.email

The completion standard here is not the appearance of the interface, but the repeatable results of “Git identity and submission ownership within the container”.

Check residual processes and files after the task ends

1
2

docker ps -a
git status --short

Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.

Select a sandbox based on mission risk

Prepare a success sample and a failure sample around “selecting a sandbox based on mission risk”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.

1

docker version

It is recommended to record the following four items:

• Pre-execution version or Git commit.
• Actual input, no secret value recorded.
• Observable output, status code or diff.
• Recovery actions and review results after recovery.

If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.

Read-only mount the host Git repository

This section addresses “read-only mounting of the host Git repository”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.

For Pi Agent, the basis for judgment is: Pi inherits the file, process, network and credential permissions of the startup user by default; Docker, Gondolin and OpenShell solve different trust boundaries and cannot be selected solely based on installation difficulty. Don’t accidentally open more permissions at this stage.

1

docker run --rm -v ${PWD}:/workspace:ro node:22 ls -la /workspace

Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.

Writable tasks use independent Worktree

Process in the following order:

1. Read the actual version and current configuration.
2. Change only one setting relevant to this section.
3. Run a read-only or revocable request.
4. Check logs, exit codes, and final files.
5. Revert the previous modification if it fails.

1

git worktree add ..\pi-task -b agent/pi-task

The completion criterion here is not the interface appearance, but “writable tasks using independent Worktree” with repeatable results.

Verify that the disconnected container cannot access the public network

1

docker run --rm --network none node:22 node -e "fetch('https://example.com').catch(e=>console.log(e.code))"

Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.

Check host residue after destroying the sandbox

Prepare a success sample and a failure sample around “checking host residue after destroying the sandbox”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.

1
2

docker ps -a
git status --short

It is recommended to record the following four items:

• Pre-execution version or Git commit.
• Actual input, no secret value recorded.
• Observable output, status code or diff.
• Recovery actions and review results after recovery.

If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.

Pi Agent FAQ

Is it possible to skip the test environment and use Pi Agent directly in the official project?

Not recommended. Complete at least one minimal success request, one intentional failure, and one recovery drill first.

The Pi Agent command can be run but the result is incorrect, where should I check first?

First check the input range, actual effective configuration and upstream response, and then check the model summary. A normal process does not mean that the business results are correct.

How to prevent Pi Agent’s keys or tokens from entering Git?

Use system environment variables, secret management, or configuration files outside the project, and search the diff before committing. Keys must be rotated after a breach is discovered.

What is the most common thing to miss when upgrading Pi Agent?

It is most easy to miss configuration format, default listening address, permission scope and cache compatibility. Save the version and verification samples before upgrading.

Pi Agent acceptance issues

Upon completion you should be able to answer the following questions:

• Which exact version are you using?
• Which directories, ports, accounts and external services can be accessed?
• How to return the successful result to the original data or Git diff?
• When the upstream fails, will it report an error, retry, or switch?
• Is it possible that the key appears in logs or history?
• How to return to the pre-modification state within ten minutes?

If any of these cannot be answered, the Pi Agent is still in trial status and should not expand permissions or tap into production automation.