Working in parallel

You can run multiple AI agents simultaneously on separate Gadget environments to explore different approaches, work on independent features, or delegate tasks without interfering with one another.

Why this works

Gadget environments are fully isolated, independently hosted instances. Each development environment is a sandboxed copy of your app with its own database, API, and runtime. There is nothing to install or provision locally. Running ggt env create gives an agent its own fully managed Gadget infrastructure in seconds, cloned from your existing environment.

Gadget development environments are unlimited, so you can spin up as many parallel environments as you need without worrying about port conflicts, shared state, or local resource limits. Each agent gets a live development environment to build and test against. If your app depends on environment variables or connected applications, copy the required variables and complete any per-environment setup before handing the workspace to an agent. When the work is done, ggt env delete tears the environment down just as quickly.

How it works

Each parallel agent gets its own:

Local workspace: An isolated copy of your codebase on disk. This can be a git worktree, a separate repo clone, or another workspace layout that fits your team.
Gadget environment: A separate cloud sandbox where the agent can run and test changes independently.

Changes from each agent stay isolated until you are ready to review and merge them.

Choosing a local workspace strategy

You need one local workspace per agent. Common options include:

Git worktrees: Fast to create, share one git repository, and work well when you want several branches checked out at once. See the git worktree docs.
Separate repo clones: Simple and familiar if you prefer complete filesystem separation for each agent.

You can automate either approach with setup scripts that create the workspace, create a Gadget environment, import variables, and hand the result to an agent.

The rest of this guide uses git worktrees, but the same ggt environment workflow applies to any separate local workspace.

Prerequisites

ggt installed and authenticated
Your Gadget app synced locally using ggt dev
Git initialized in your project directory

Example setup with git worktrees

1. Create a local workspace

From your main app directory, create a new worktree for the agent:

terminal
git worktree add ../agent-feature
cd ../agent-feature

This creates a new directory with a new branch checked out from your current HEAD. Because the directory name is agent-feature, git uses that same name for the new branch. If you prefer separate clones instead of worktrees, create that clone here and continue with the same ggt steps below.

2. Create a new Gadget environment

Create a dedicated Gadget environment for the workspace:

terminal
ggt env create agent-feature --use

The --use flag updates the workspace's .gadget/sync.json so subsequent ggt commands in this directory target the new environment automatically.

If you are creating environments from an automated script, pass --app explicitly:

terminal
ggt env create agent-feature --app my-app --use

3. Copy environment variables

Copy environment variables from your development environment to the new one. --include-values copies non-secret values, but secret values are not copied:

terminal
ggt var import --from development --all --include-values

Secret variables

Secret variables cannot be read back once set, so ggt var import --include-values does not copy them. Set any required secrets manually after importing: ggt var set MY_SECRET=value --secret

4. Push your local code to the new environment

terminal
ggt push --force

The --force flag discards any remote changes and replaces the environment with your local files. Since this is a freshly created environment, this is safe.

5. Start `ggt dev`

If your agent needs to test code changes against the running Gadget environment, start ggt dev in the workspace directory:

terminal
ggt dev

ggt dev runs until you stop it. While it is running, changes made locally and changes made in the cloud development environment are synced automatically.

6. Start your agent

Open Claude Code, Codex, or your AI coding tool of choice in the workspace directory. The agent will develop against the new environment without affecting the other agent workspaces or environments you are using.

Running multiple agents

Repeat the setup for each additional agent:

terminal
# From your main app directory
git worktree add ../agent-feature-2
cd ../agent-feature-2
ggt env create agent-feature-2 --use
ggt var import --from development --all --include-values
ggt push --force

If you do this often, wrap these commands in a setup script or use a tool that manages worktrees and agent workspaces for you. For example, tools like Codex or OpenCode provide with scripted workspace setup, and other agent platforms can automate worktree creation before handing the workspace off to an agent.

Each workspace and environment is fully independent. Agents cannot interfere with each other.

Reviewing and merging changes

Once an agent has completed its work, review the changes in that workspace and then follow your team's normal process for opening pull requests, running tests, reviewing code, merging changes, and shipping updates.

If multiple agents worked on overlapping files, resolve conflicts using the same workflow you use for any other branch or pull request.

Cleaning up

Remove the workspace and delete the Gadget environment when finished:

terminal
# Delete the Gadget environment
ggt env delete agent-feature --force

# Remove the git worktree
git worktree remove ../agent-feature

Tips

Name environments clearly: Use descriptive names like agent-checkout-redesign or codex-auth-fix to track what each environment is for.
Keep names aligned: Using the same name for the workspace, git branch, and Gadget environment makes it much easier to review, clean up, and understand which agent owns which changes.
Check variable keys: Run ggt var list in the new workspace to verify the environment has the variables it needs before starting your agent.
Automate the setup: The ggt env create, ggt var import, and ggt push commands are straightforward to wrap in shell scripts or init scripts. You can build these scripts yourself or have a coding agent such as Codex generate them so new worktrees and Gadget environments can be created consistently.