Agent sandboxes

We recommend running AI agents in a sandbox. It limits their access to files, secrets, and tools on your computer, while emisar extends that control to infrastructure and third-party tools.

Choose a sandbox#

We recommend co:op for most local setups. It is a free, open-source tool that supports Codex, Claude Code, Gemini CLI, and Grok CLI and lets you control which files, secrets, and tools the agent can access. It can also coordinate work across models and providers, switch providers during a session, and manage shared task queues.

Connect a sandbox#

1. Open Connect an agent, then choose your sandbox under Agent sandboxes.
2. Follow the steps shown there.
3. Start the agent and send the example prompt. When the console shows Agent connected, open Audit to confirm the action, runner, operator, and result.

co:op#

What you need#

co:op runs the agent in a container on macOS or Linux. Use Apple container, Docker, or Podman as the runtime. The console shows how to install the bridge in the image and keep its rotated credentials in a named volume.

Recommendations#

• Only add the files, secrets, and host tools the agent needs. Use .coopignore for project-specific secrets; .gitignore does not hide them from the agent.
• Anything you mount or pass into the sandbox remains available to the agent. Keep production credentials and privileged host sockets out.
• Run coop doctor after setup to verify the sandbox. Run coop check-secrets regularly to find secrets hidden in your repository.

Docker Sandboxes#

What you need#

Docker Sandboxes runs supported coding agents in a microVM on a supported macOS or Ubuntu host and requires a Docker account. Its MCP gateway connects them to the emisar bridge on the host without copying the emisar key into the VM.

Limits & risks#

• Docker shares the project directory with the VM, so the agent can see and potentially leak anything stored there, including secrets in .env files and temporary artifacts. For stronger isolation from local files, use co:op.
• The registered MCP launcher runs on the host with your permissions. Keep it and its environment file outside the shared project and do not let the agent edit them.
• We recommend reviewing the sandbox's network policy and allowing access only to the services the agent needs.

nono#

What you need#

nono can run any terminal agent under an operating-system profile on macOS or Linux. Use a suitable maintained profile from nono's profile registry and keep the provider credentials where that profile expects them.

Limits & risks#

• The agent can see any file, secret, tool, or network destination allowed by the profile, including everything in its working directory.
• The agent can read the emisar key in its MCP configuration. Allow network access only to the services the agent needs.
• Review the profile after adding file, command, environment-variable, or network access.

Key rotation#

Rotate the key manually from AI agents, replace it in the private agent configuration, and start a fresh nono session. Do not give the sandbox the whole credential directory to automate this.

Dev Containers#

What you need#

A Dev Container runs a CLI agent and the emisar bridge inside a project that already has a working .devcontainer setup. You need Docker and either the VS Code Dev Containers extension or the standalone Dev Containers CLI. Run the agent as a non-root user inside the container.

Limits & risks#

• The agent can see and potentially leak anything mounted into the container, including secrets in .env files and temporary artifacts. Mount only the files it needs. For stronger isolation from local files, use co:op.
• VS Code can share Git credentials or forward an SSH agent into the container. Review its credential-sharing settings before starting the agent, and never mount the host's Docker socket.
• The default configuration does not restrict outbound network access. We recommend allowing access only to the services the agent needs.

Rebuilds and rotation#

Keep the bridge's named volume when rebuilding the container so rotated credentials are retained. If you remove the volume or private configuration, create a fresh key from AI agents and reconnect.