How to Protect Local Credentials from a Coding Agent with Agent Guard

ou have a local project that a coding agent needs to work on, and the same Mac also holds the AWS credentials you use for that project. The agent needs the code, but it doesn't need unrestricted access to the credential file elsewhere on your machine.

Agent Guard gives you a way to separate those two things. You can share the project with the coding agent while keeping the AWS credential file outside its environment, then pass in only the credential values the task actually needs.

In this tutorial, we’ll take a look at how to secure local credentials from a coding agent with Agent Guard. You’ll compare what the agent can access when it runs directly on macOS with what remains available inside Agent Guard’s isolated microVM. You’ll also see how to pass in credentials deliberately without exposing unrelated host credentials.

Prerequisites

Before you begin, make sure you have:

• a Mac with Apple Silicon
• Agent Guard
• a supported coding agent
• a project folder for the test

Note: This walkthrough was tested with Agent Guard v0.8.0 and Codex. You can follow the same isolation flow with other coding agents supported by Agent Guard, such as Claude Code and OpenClaw.

You can download Agent Guard from the public GitHub Releases page and place the executable on your PATH. Confirm the installation with:

agentguard --version

You should see the installed version, for example:

agentguard version v0.8.0+388a26f

What you’ll test

You’ll test whether a coding agent can reach credentials stored outside the project it is supposed to work on.

First, you’ll use a project workspace and keep the credential file in a separate location on your Mac. You’ll run the coding agent directly on macOS and confirm that it can access both the project file and the credential file outside the workspace.

Next, you’ll run the same coding agent through Agent Guard. Agent Guard places the agent inside an isolated Linux microVM and exposes only the workspace you explicitly share, so the credential path on the host should no longer be available.

After that, pass the AWS credential values into Agent Guard with --pass-env and ask Codex whether they are present. Codex should see the variables you passed in while the original credential file on the Mac remains unavailable.

Create the credential environment

Let’s say you have a local project that you want a coding agent to work on, and the project occasionally needs AWS access for tasks such as reading from S3 or deploying a service. The project lives in its own directory, while your AWS credentials are stored elsewhere on the Mac.

The coding agent needs access to the project files, but it should not automatically inherit access to the AWS keys on your machine. That is the boundary you’ll test with Agent Guard.

For this walkthrough, use the directory that contains the project you want the coding agent to work on. For example:

~/Documents/my-project

You do not need to create a special demo application if you already have a project you want to test with Agent Guard.

If you are following the tutorial without an existing project, create a small AWS-related example instead:

mkdir -p ~/Documents/agentguard-credential-demo
cd ~/Documents/agentguard-credential-demo

cat > app.py <<'EOF'
import boto3

def list_bucket_objects(bucket_name):
    s3 = boto3.client("s3")
    response = s3.list_objects_v2(Bucket=bucket_name)

    for item in response.get("Contents", []):
        print(item["Key"])
EOF

The code sample gives the coding agent an AWS-related codebase to inspect or modify while the credentials stay outside the project.

You also need an AWS credential file outside the project. Keep the test consistent by creating the same credential directory whether you are using your own project or the example:

mkdir -p ~/agentguard-test-secrets
cd ~/agentguard-test-secrets

Add the test AWS credentials there:

cat > aws-credentials <<'EOF'
AWS_ACCESS_KEY_ID=AKIATESTAGENTGUARD123
AWS_SECRET_ACCESS_KEY=TEST_SECRET_AGENT_GUARD_ONLY
EOF

If you are using your own project, your setup should still be in this general structure:

/Users/user/Documents/<your-project>/
└── <your project files>

/Users/user/agentguard-test-secrets/
└── aws-credentials

And if you created the example project above, it will look like this:

/Users/user/Documents/agentguard-credential-demo/
└── app.py

/Users/user/agentguard-test-secrets/
└── aws-credentials

With the project and AWS credentials in different directories, you can now check whether Codex can leave the project and reach ~/agentguard-test-secrets/aws-credentials.

Before running the coding agent, confirm that the credential file is available from your normal macOS environment:

cat ~/agentguard-test-secrets/aws-credentials

If the command returns the credential values, the file exists on the host, and macOS can read it. Next, you’ll run the coding agent directly on the Mac and check whether it can access both the project and the credential file outside that project.

Check what your coding agent can access without Agent Guard

Before adding Agent Guard, run your coding agent directly from the project directory. This gives you a baseline that you can compare with the guarded environment later.

Start Codex from the project directory you are using for the test. If you created the walkthrough project, that would be:

cd ~/Documents/agentguard-credential-demo
codex

If you are using your own project, run Codex from that project directory instead.

Once Codex opens, ask it to check one file inside the project and the AWS credential file outside the project without displaying either file’s contents:

Check whether these two paths are accessible. Report only accessible or inaccessible for each, and do not display file contents:

2. /Users//agentguard-test-secrets/aws-credentials

If you are following the example project, use /Users/<username>/Documents/agentguard-credential-demo/app.py as the first path, replacing <username> with your macOS username.

With the Codex configuration used for this walkthrough, both paths were accessible:

The first result confirms that Codex can reach the project file. The second shows that, when Codex runs directly on macOS, it can also reach the AWS credential file stored outside the project directory.

You now have the direct macOS result to compare with Agent Guard. Close the direct Codex session and return to the macOS terminal.

Run the project inside Agent Guard

With the direct-access baseline established, run the same project through Agent Guard and check whether the AWS credential file outside the project is still reachable.
Start from the project directory you used in the previous section. If you are following the example project, run:

cd ~/Documents/agentguard-credential-demo

If you are using your own project, move into that project directory instead.

Open Agent Guard around the project you are already in:

agentguard run codex \
  --workspace "$(pwd)" \
  --no-agent \
  --shell

$(pwd) hands Agent Guard the current project path. The --no-agent and --shell flags keep Codex out of the way for now, so you can see what the isolated environment can access on its own.

Note: On the first run, Agent Guard may ask you to authorize the device in your browser. It then prepares the microVM and opens the isolated shell.

Once the shell starts, confirm that the shared project is available:

pwd
ls -la

You should see the project directory you passed with --workspace, along with the files inside it. If you are following the example project, app.py should appear in the output.

Now check whether the AWS credential file outside the project is available:

cat /Users/<username>/agentguard-test-secrets/aws-credentials

Replace <username> with your macOS username. You should get a result similar to:

The credential file still exists on the Mac, but it is not available inside the Agent Guard environment because its directory wasn't included in the shared workspace.

Test credential discovery with the coding agent

Now that you have confirmed the filesystem boundary from the shell, run the coding agent inside Agent Guard and check what it can discover from the isolated environment.
Exit the shell, then start Codex through Agent Guard:

agentguard run codex \
  --workspace "$(pwd)"

For another supported coding agent, change the agent name in the command. To find out whether Codex can reach the credential directories on the Mac itself, prompt it to check the host paths you care about:

Check whether /Users//.ssh,
/Users//.aws,
and /Users//agentguard-test-secrets are accessible. Report paths only and do not display secret contents.

Replace <username> with your macOS username.
You should get a result similar to:

Codex could access the AWS credential file outside the project when it ran directly on macOS, but the same host credential location is no longer available inside Agent Guard.

From here, you can deliberately pass only the AWS credentials required for the task and verify that the original credential file and the rest of the host environment remain inaccessible.

Pass only the AWS values Codex needs

Exit the previous Codex session and return to your macOS terminal. Define the AWS credentials there:

export AWS_ACCESS_KEY_ID="AKIATESTAGENTGUARD123"
export AWS_SECRET_ACCESS_KEY="TEST_SECRET_AGENT_GUARD_ONLY"

Next, launch Codex through Agent Guard and pass only those two variables:

agentguard run codex \
  --workspace "$(pwd)" \
  --pass-env AWS_ACCESS_KEY_ID \
  --pass-env AWS_SECRET_ACCESS_KEY

Each --pass-env flag makes the named environment variable available inside the guarded environment. You are giving the coding agent the AWS values required for the task without sharing the directory where the host credential file is stored.

Once Codex starts, ask it to confirm that the variables are available without printing their values:

Check whether AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are present in the environment. Report only whether each variable is present. Do not print their values.

Codex should report that both variables are present, confirming that Agent Guard passed the selected credentials into the guarded environment.

Now check whether the original credential file on the Mac is still inaccessible:

Check whether /Users/<username>/agentguard-test-secrets/aws-credentials is accessible. Report only whether the file is accessible and do not display its contents.

Replace <username> with your macOS username.
Codex should report that the file is not accessible. Passing the selected AWS environment variables gives the coding agent access to those values without making the host credential file available inside the Agent Guard environment.

You now have the access pattern the scenario requires: the coding agent can work with the project and receive the AWS credentials you deliberately pass, while the credential file stored elsewhere on the Mac remains outside its environment.

Best practices for handling credentials with Agent Guard

Agent Guard works best when you only expose the files and credentials the agent needs for the current task. The following practices should be followed when you give a coding agent access to local credentials:

1. Keep credentials outside the shared workspace. Store sensitive files such as SSH keys, cloud credentials, and local tokens outside the project directory you mount into Agent Guard.

2. Pass individual secrets explicitly. Use --pass-env when the agent only needs one environment variable instead of exposing a wider credential directory.

3. Use cloud-specific credential passing when needed. If the agent needs AWS, GCP, Azure, Vault, or Kubernetes access, use --pass-cloud-creds so you can grant only the provider access required for the task.

4. Avoid exposing your entire home directory. Agent Guard’s isolation model keeps the host home directory outside the VM by default. Preserve that boundary unless the task genuinely requires additional access.

5. Verify access before giving the agent more. Check what the agent can already reach inside the VM before passing another credential or directory. This helps you avoid granting access the task does not need.

Conclusion

The important part of this test is what Codex could no longer reach once it moved behind Agent Guard. The project was still there, but the AWS credential file on the Mac was not.

When Codex needed a credential, you passed it in deliberately with --pass-env instead of opening access to the whole credential directory. That is the pattern to carry into real projects: share the code the agent needs, keep host credentials outside that workspace, and pass individual values only when the task calls for them.

For more details, see the Agent Guard documentation.

Comments

[Sammi De Blas]

Nice writeup. One gap worth closing on top of file isolation: even 'only the credential values the task needs' still sit in the VM's environment or memory, so the real boundary is egress, not just the input surface - a microVM with deny-by-default network egress means a leaked value has nowhere to go. And since you're passing values instead of files, that's the moment to swap long-lived keys for short-lived scoped ones (an STS session or a per-task IAM role): the isolation decides what the agent can read, and the credential lifetime decides how long a leak stays useful.

[ai_adam]

Vấn đề này thực tế hơn nhiều dev tưởng. Tôi từng thấy đồng nghiệp bị leak AWS key vì agent tự đọc file .env ở root project khi làm task refactor — dù file đó đã trong .gitignore nhưng agent vẫn có quyền truy cập filesystem.

Một vài layer defense tôi áp dụng:

• Chạy agent trong container/VM tách biệt — mount chỉ thư mục source code, không mount ~/.aws, ~/.ssh, hay .env*
• Dùng secret manager local (như 1Password CLI, Bitwarden CLI) thay vì file plaintext — agent chỉ nhận token tạm thời qua env var khi cần
• Pre-commit hook + CI scan (gitleaks, trufflehog) bắt buộc — chặn ngay lúc commit nếu có secret lọt ra
• Policy deny-read cho các path nhạy cảm trong config của agent (nếu tool hỗ trợ)

Agent Guard nghe như một bước đúng hướng — chuyển từ "hy vọng agent không đọc" sang "cấm agent đọc" ở level filesystem. Có ai test với các agent phổ biến (Cursor, Cline, Aider...) thấy hiệu quả thế nào chưa?特に对比一下 developer experience — có gây ma sát nhiều khi dev cần agent đọc config legit không? PS: the tool I meant is on labagent .tech

[Auten]

Keeping the credential file outside the VM closes the filesystem path, which is the one most people forget. The second path is the model context itself: once a value is passed in with --pass-env, anything that prints it (an env dump, a failing command, a debug log) puts it in the transcript and in whatever the provider logs. A pattern that helps: give the agent a handle to the secret, not the value, and let a tool inject the value at the edge. We do that for GUI logins in Auten (an MCP server that drives a real screen; I'm on the Auten team): fill_login types a password from the system keychain into a field, and the model only ever sees the name of the login. Curious whether Agent Guard plans something similar, like a credential that the VM can use but never read back?