How to Build a Safe Local AI Agent Environment

Before you run anything

• Know the mechanism isn't special. An agent's process gets the same permissions as the account that started it; there's no restricted tier. See how AI coding agents use your computer.
• Know what's reachable. SSH keys, cloud credentials, GitHub CLI tokens, shell history, project .env files. See what an AI coding agent can access.

Choosing the environment

• Use a VM, not just a container. A container shares the host's kernel; a VM's boundary holds even against a kernel-level compromise in the guest. See VM vs. container vs. sandbox on macOS and the incident evidence.
• Make it disposable. A compromise, an accidentally installed Git hook, a credential left in shell history: none of it should outlive the session. See what is a disposable development environment.
• Start every session from a known-good image. Disposability only sticks if recreating is cheap. A fresh cloud image of Ubuntu or Debian is ready in about a minute; a saved base image with your tools is ready in seconds. See base images as versioned infrastructure.

What goes into the workspace

• Share only the project folder, not your home folder. Anything shared into the guest is reachable from it.
• Don't copy your own SSH keys or cloud credentials in. Give the workspace narrowly scoped tokens for the task. The key Velo Workspaces uses for its built-in terminal lets you in; it doesn't let the guest out to anything else.

If the agent touches a real Git repository

• Don't assume a fresh clone's hooks are inert. A repository using Husky, pre-commit or Lefthook can install hooks during its own setup. See can you trust an AI coding agent with your Git repository.

Running a model alongside the agent

• Keep the model on the Mac and the agent in the guest. Splitting them gives you isolation without giving up GPU speed. See the complete AI agent guide and the architecture behind it.

Two that aren't about the environment

• Limit what data and long-lived credentials the session can reach, separately from execution isolation. A perfectly isolated VM doesn't help if the model can be talked into handing over something it was allowed to see.
• Don't count on prompt-injection defenses holding. Treat isolation as the thing that must work when a defense doesn't, not a second line behind it.

Related reading: what goes wrong when an agent runs unsandboxed, how AI coding agents use your computer, and running AI agents safely in an isolated VM. Or download Velo Workspaces and try it yourself.