How to Run Multiple AI Coding Agents Safely with Git Worktrees and Isolated Permissions

Eva Wong

IceWhale author

Eva Wong is the Technical Writer and resident tinkerer at ZimaSpace. A lifelong geek with a passion for homelabs and open-source software, she specializes in translating complex technical concepts into accessible, hands-on guides. Eva believes that self-hosting should be fun, not intimidating. Through her tutorials, she empowers the community to demystify hardware setups, from building their first NAS to mastering Docker containers.

How to Run Multiple AI Coding Agents Safely with Git Worktrees and Isolated Permissions - Zima Store Online

Give each coding agent its own branch and working directory, then separately restrict the process's files, credentials, and network access. Git worktrees reduce accidental interference between edits, but they are not security sandboxes. A safe parallel workflow needs both understandable repository state and enforceable runtime permissions.

This guide shows local worktree commands, task-scoped access, independent test setup, and a human-reviewed integration sequence. Use a repository you own or are authorized to modify, and begin with disposable tasks. The procedure is tool-neutral: a coding-agent interface may automate parts of it, but the underlying boundaries still need to be checked.

What Goes Wrong When Agents Share One Workspace?

Two agents can overwrite uncommitted edits, change the same dependency file, or interpret another task's temporary state as the project's intended design. They can also run tests against a directory that changes while the test is executing. The resulting failure may be difficult to reproduce because neither agent tested a stable revision.

The problem extends beyond source files. Shared ports, database names, caches, fixture directories, and background processes can create interference even when the diffs touch different modules. One agent may stop a service another is using, or regenerate files from a schema that is still being edited.

Our multi-agent coordination explainer describes how task boundaries and dependencies reduce that interference. Before creating more workers, write down each assignment's outcome, permitted edit area, dependencies, and acceptance tests. “Work on the same feature together” is not a sufficient contract for independent changes.

A separate directory makes accidental interference less likely; a separate security context controls what the process can reach. Keep those purposes distinct so you do not mistake successful branch separation for protection of private files or production services.

When Should You Use Worktrees Instead of Separate Clones?

Git worktrees are useful when several branches of one repository need simultaneous working directories. Separate clones can be preferable when an experiment needs more independent repository configuration or a different remote setup. Neither option, by itself, limits the operating-system user's access to secrets or other directories.

Choose based on the actual workflow. Worktrees can make branch-based review convenient, while separate clones may make some destructive experiments easier to contain at the repository level. For untrusted code or broader execution risk, use an appropriately isolated runtime regardless of how the source was checked out.

Boundary	What it helps separate	What it does not automatically separate
Branch	Proposed commit history	Files being edited in one shared working directory
Worktree	Working files and branch checkout	Host privileges, credentials, external databases, and network access
Separate clone	Repository checkout and much local repository configuration	Operating-system identity or access to the host home directory
Container or sandbox	Resources permitted by its actual configuration	Host exposure through mounts, sockets, privileges, or shared secrets
Dedicated OS identity	Access governed by that account's permissions	Every possible escape path or incorrectly granted external permission

The table is a planning aid, not a security certification. Test the boundary you intend to rely on, including the files and services visible from the agent's actual shell.

Separate edits, access, and acceptance — Illustrative diagram: branch isolation, runtime permissions, testing, and acceptance are independent controls.

Cover: Conductor official brand-kit wordmark, used unchanged for editorial identification. Product marks remain with their owner; no affiliation is implied.

How Do You Create One Branch and Worktree per Agent?

Start from a known, reviewed base. Save existing work before changing branches, and inspect the working directory rather than assuming it is clean. The following example assumes a local repository whose reviewed base is main; use the appropriate base for your project. Do not copy a command with the wrong branch name and then force it to succeed.

git status --short
git branch --show-current
git worktree list
git switch main
git worktree add -b agent/docs ../agent-docs main
git worktree add -b agent/tests ../agent-tests main
git worktree list

Assign each agent the path to its own worktree and a bounded task. Record the base commit and explain which shared files require coordination. Do not copy the entire personal development environment into each directory as a convenience; that can duplicate credentials and unrelated private material.

Use this end-to-end sequence:

Confirm a clean or safely preserved repository state and choose the reviewed base.
Create a unique branch and worktree for each assignment.
Provide only the task's necessary context and a clear completion contract.
Configure dedicated, scoped credentials only when the task requires them.
Give tests distinct temporary paths, ports, and disposable service state.
Inspect each diff and test result before proposing integration.
Merge through the project's human review and repository controls.
Preserve needed evidence, remove completed worktrees normally, and revoke temporary access.

These commands create repository state; they do not configure sandboxing. If an agent tool has its own workspace manager, inspect the resulting branches and paths so the same contract remains understandable outside the interface.

How Should Keys, Environment Files, and Tokens Be Isolated?

A worktree should not inherit a developer's entire credential set. Prefer a dedicated identity with only the repository and service permissions needed for the task. Keep secrets in approved storage and pass them through the tool's supported mechanism, not in a prompt, task file, or committed .env file.

GitHub's token documentation explains token permissions and lifecycle. Select the narrowest practical scope, an appropriate expiration, and a way to revoke it. A token needed to read source does not imply permission to change workflow files, merge pull requests, or administer a repository.

Environment variables are a delivery mechanism, not a complete isolation boundary. A child process may inherit them, and a debugging command or log can expose them. Review which variables reach each worker and avoid sharing production values with tests. Use synthetic credentials for services that can be simulated.

The OWASP secrets-management guidance provides background on controlling access and rotation. If an agent reads a secret it did not need, treat that as a configuration issue even if no disclosure is observed. The environment should make unnecessary access impossible or deliberately restricted, rather than relying on the model to avert its attention.

How Can Containers or Sandboxes Limit Access?

Inspect the actual configuration: user identity, mounted paths, network policy, privileges, sockets, and available credentials. A container with the host's home directory and container-engine socket mounted into it may have access far beyond its task folder. A “sandbox” label is not evidence that those resources are restricted.

The Docker security overview explains important runtime considerations. Use the platform's supported controls to reduce privileges, mount only necessary data, and separate service state. Test whether the worker can access locations that should be out of scope. A successful denial is useful evidence that a control is active.

Network access should reflect the assignment. A task may need a package registry and a repository host without needing arbitrary outbound destinations or production databases. Apply controls at an enforceable layer and document exceptions. Do not disable certificate checks to make dependency installation work; resolve the actual trust or connectivity problem.

The rootless Docker documentation describes one option for reducing daemon and container privilege. It does not make every workload harmless or remove the need to review mounts and secrets. Choose isolation appropriate to the code being executed and the value of the host environment.

How Should Changes Be Reviewed and Merged?

Review uncommitted work as well as commits. An agent may report a task complete while leaving relevant files outside its commit or while testing a working directory that differs from the proposed branch. Ask it to identify the actual result and then inspect it independently.

git -C ../agent-docs status --short
git -C ../agent-tests status --short
git diff --stat main...agent/docs
git diff main...agent/docs
git diff --stat main...agent/tests
git diff main...agent/tests

Run the project's relevant checks in each worktree and again on the integrated revision where interaction matters. Review shared contracts, generated files, and dependency updates. If the base changes during review, identify which evidence is stale. Do not preserve an approval's appearance while changing the code it was meant to approve.

GitHub's protected-branch documentation describes repository-side controls that can complement the workflow. Keep human acceptance of consequential changes separate from the agent's ability to create a proposal. A review agent can provide another perspective without becoming the sole authority to merge.

Our agentic-autofix review guide provides a related acceptance checklist. When a conflict arises, resolve the intended behavior first. Asking a model to remove conflict markers without explaining the contract can produce a clean file containing the wrong combined behavior.

After accepted work is safely preserved and integrated, use ordinary cleanup:

git worktree list
git worktree remove ../agent-docs
git worktree remove ../agent-tests
git branch -d agent/docs
git branch -d agent/tests

Do not add force flags to bypass a refusal. A dirty worktree or a branch Git does not consider merged needs inspection. Preserve unfinished changes and understand the history before deciding what can be removed.

What Should You Monitor During Parallel Runs?

Watch task ownership, process lifetime, resource use, external requests, and the queue of results waiting for review. A worker that keeps running after a task ends can continue using credentials or modifying shared services. Establish how it is stopped and how you confirm that it has actually stopped.

Set reasonable budgets and escalation conditions for each assignment. Repeated dependency failures, unexpected permission requests, or edits outside scope should prompt inspection rather than unlimited retries. Keep logs useful but avoid recording secret values or unnecessary private content.

Our personal-agent permission checklist helps prepare the access review. The Conductor transition analysis also illustrates why work should remain portable: commits, task state, and review evidence need to survive a change in the orchestration product.

Before starting another batch, check that temporary credentials have been revoked where appropriate, background services are accounted for, and completed branches have a known disposition. Measure accepted work and reviewer effort, not just the number of agents that were active. If integration is the bottleneck, reduce work in progress rather than adding more output to the queue.

Before cleanup, check the recoverable-file workflow for material outside Git history. An untracked dataset, local configuration file, or external service state may need its own recovery plan.

FAQ

Can two agents use one branch safely?

It is possible to coordinate shared work, but independent agents should normally receive distinct branches and working directories. Otherwise, edits and test results become difficult to attribute and reproduce.

Does adding `.env` to `.gitignore` protect its contents from an agent?

No. Ignore rules affect Git tracking, not filesystem read permissions. Keep unnecessary secrets outside the worker's accessible environment.

Should every agent have a token that can merge changes?

No. Grant only permissions needed for the assignment. Creating a proposed change and accepting it into the protected branch are different authorities.

What if worktree removal refuses to proceed?

Inspect the directory for uncommitted or untracked work and preserve what matters. Do not use force as a routine cleanup step.

Is a passing test in each branch enough?

Not when the changes interact. Run relevant checks against the actual integrated revision and inspect cross-boundary behavior.

Conclusion

Safe parallel coding combines source isolation with runtime and credential controls. Worktrees make changes easier to separate and review, while dedicated permissions and appropriately configured sandboxes limit what an agent can reach.

Begin from a clean base, give each assignment a clear owner and contract, and integrate only reviewable results. Preserve evidence before cleanup, revoke temporary access, and expand concurrency only when accepted outcomes justify the coordination cost.