Local Development Setup

This guide covers setting up your local environment for developing and debugging AgentVisor™ agents without sandbox isolation.

Why Disable the Sandbox?

When developing agents, you'll often want to:

Set breakpoints and step through code
Use interactive debuggers (VS Code, PyCharm)
Get faster iteration cycles without container overhead
Access your local filesystem for debugging

The --sandbox=none mode runs your agent directly in your Python environment, bypassing container isolation. This enables standard Python debugging workflows.

Development Only

Running with --sandbox=none provides no security isolation. Your agent has full access to your filesystem and network. Use this mode only for development and debugging — never in production.

Prerequisites

Before using --sandbox=none, you need:

Python 3.10 or later
A Python virtual environment
The AgentVisor SDK and protobuf bindings installed

Setup Steps

1. Create a Virtual Environment

Create a virtual environment in your agent project directory:

cd my-agent
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows

2. SDK Installation

When running agents with --sandbox=none, the SDK is not automatically provided. Install it manually in your virtual environment.

Not on PyPI

agentvisor is not published to PyPI — that package name is already registered by an unrelated third-party project. Install the SDK from the wheel attached to each GitHub release instead.

Download the wheel for the release you want (the proto/gRPC bindings are bundled into it, so this is the only file you need):

# Replace VERSION with a tag from https://github.com/manetu/agentvisor/releases
VERSION=v0.6.0-5.215

curl -fsSL "https://github.com/manetu/agentvisor/releases/download/${VERSION}/checksums.txt" \
    -o checksums.txt
WHEEL=$(awk '$2 ~ /^agentvisor-.*\.whl$/ {print $2}' checksums.txt)
curl -fsSL "https://github.com/manetu/agentvisor/releases/download/${VERSION}/${WHEEL}" -o "${WHEEL}"

Installation Variants

Install the wheel with the extras your agent needs:

pip install "${WHEEL}[langgraph]"

Extra	Adds
(none)	Core features (checkpointing, logging, store, MCP)
`langgraph`	LangGraph checkpointer, graph discovery
`langchain`	LangChain MCP tool integration
`crewai`	CrewAI crew discovery, MCP tools adapter
`adk`	Google ADK agent discovery, session adapter
`strands`	Strands Agents runner, schema registration, MCP tools adapter
`tracing`	OpenTelemetry tracing helpers
`all`	All integrations

For most LangGraph-based agents, pip install "${WHEEL}[langgraph]" installs:

agentvisor — Core SDK (checkpointer, store, streaming, logging), with bundled protobuf bindings
LangGraph integration (checkpointer, graph discovery)

When You Need Manual Installation

Running agentvisor serve --sandbox=none for local debugging
Running agentvisor run --sandbox=none for quick iteration
Developing without containerization

When You Don't Need Manual Installation

Using agentvisor serve (default sandbox modes)
Using agentvisor run with docker/gvisor
Building with agentvisor build (SDK pre-installed in guest image)

requirements.txt and the SDK

warning

This applies to --sandbox=docker/--sandbox=gvisor, not --sandbox=none — in --sandbox=none mode there's no guest image at all; you manage the SDK yourself as described above.

For sandboxed modes, don't add a bare agentvisor to your agent's requirements.txt — the guest image already has a compatible version pre-installed with matching protobuf bindings, and reinstalling it risks a version mismatch against the guest runtime's gRPC contract.

If your agent needs an optional extra — agentvisor[tracing] (see Agent Tracing), agentvisor[crewai], agentvisor[adk], etc. — do add that to requirements.txt. pip layers the extra's dependencies onto the already-installed base package rather than reinstalling agentvisor itself.

Agent Dependencies Installed Automatically

AgentVisor automatically installs your agent's requirements.txt if the file exists. You only need to:

Create a venv with the AgentVisor SDK installed
Activate the venv when running agentvisor serve or agentvisor run

The CLI handles installing your agent's dependencies for you.

3. Verify Installation

python -c "from agentvisor.langgraph import AgentVisorCheckpointer; print('SDK OK')"

Running with the Sandbox Disabled

With your environment set up, run your agent:

# Make sure your venv is activated
source .venv/bin/activate

# Run the agent
agentvisor serve . --sandbox=none

Or for a single execution:

agentvisor run . --sandbox=none --input '{"messages": [{"role": "user", "content": "Hello"}]}'

Complete Example

Here's the full workflow for a new agent project:

# Create project from template
agentvisor template create langgraph/chatbot-agent
cd chatbot-agent

# Start supporting services (Temporal, etc.)
docker compose up -d

# Set up Python environment
python3 -m venv .venv
source .venv/bin/activate

# Install the SDK from the release wheel (agentvisor isn't on PyPI — see
# SDK Installation above); agent dependencies are installed automatically by the CLI
VERSION=v0.6.0-5.215
curl -fsSL "https://github.com/manetu/agentvisor/releases/download/${VERSION}/checksums.txt" \
    -o checksums.txt
WHEEL=$(awk '$2 ~ /^agentvisor-.*\.whl$/ {print $2}' checksums.txt)
curl -fsSL "https://github.com/manetu/agentvisor/releases/download/${VERSION}/${WHEEL}" -o "${WHEEL}"
pip install "${WHEEL}[langgraph]"

# Run without sandbox isolation
agentvisor serve . --sandbox=none

Interactive Debugging

For step-by-step debugging with breakpoints and variable inspection, AgentVisor supports pluggable debug providers.

Choosing a Debug Provider

Provider	Protocol	Best For	Install
`debugpy` (default)	DAP	VS Code, any DAP client	`pip install debugpy`
`pydevd`	pydevd	PyCharm native features	`pip install pydevd-pycharm`

debugpy uses the Debug Adapter Protocol (DAP) and works with VS Code, PyCharm, and any DAP-compatible client. The agent listens for debugger connections. This is the default provider.

pydevd uses PyCharm's native debug protocol, providing Cython-optimized code evaluation, better Django/Flask template debugging, and PyCharm's advanced variable rendering. Like debugpy, the agent listens and PyCharm connects — pydevd just uses its own wire protocol instead of DAP.

Using Debug Mode

Start your agent with the --debug flag:

agentvisor run ./my-agent --sandbox=none --debug --input '{"messages": [{"role": "user", "content": "Hello"}]}'

You'll see:

Debug mode enabled. Debugger will listen on port 5678.
Attach your IDE debugger to localhost:5678 before the agent times out.

The agent waits for your debugger to attach before executing. This gives you time to set breakpoints and start your IDE's debugger.

Custom port:

agentvisor run ./my-agent --sandbox=none --debug --debug-port=5679

Server mode:

agentvisor serve ./my-agent --sandbox=none --debug

Single Debug Session

Only one agent can bind to the debug port at a time. In serve mode with concurrent requests, only the first agent will successfully attach. For debugging specific scenarios, use agentvisor run instead.

Environment variables:

AGENTVISOR_GUEST_DEBUG_ENABLED=true agentvisor run ./my-agent --sandbox=none
AGENTVISOR_GUEST_DEBUG_PORT=5679 agentvisor run ./my-agent --sandbox=none
AGENTVISOR_GUEST_DEBUG_PROVIDER=pydevd agentvisor run ./my-agent --sandbox=none --debug

VS Code Setup

Install debugpy in your virtual environment:

pip install debugpy

Create or update .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "AgentVisor: Attach to Agent",
      "type": "debugpy",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "${workspaceFolder}"
        }
      ],
      "justMyCode": false
    }
  ]
}

Debugging workflow:

Start the agent with --debug flag
Set breakpoints in your Python files (click in the left margin)
Open Run and Debug view (Ctrl+Shift+D / Cmd+Shift+D)
Select "AgentVisor: Attach to Agent" and click play (F5)
Debug using F10 (step over), F11 (step into), F5 (continue)

PyCharm Setup

PyCharm supports two debugging approaches. Choose based on your preferences:

Approach	Connection Model	Advantages
Option A: DAP (debugpy)	Agent listens, IDE connects	Standard protocol, simpler setup
Option B: Native (pydevd)	Agent listens, IDE connects (pydevd protocol)	Cython speedups, native PyCharm features

Option A: Debug Adapter Protocol (debugpy)

Install debugpy in your virtual environment:

pip install debugpy

Configure PyCharm:

Open Run → Edit Configurations...
Click + → Python Debug Server
Configure:
- Name: AgentVisor: Attach (DAP)
- IDE host name: localhost
- Port: 5678
Add Path mappings:
- Local path: /path/to/your/project
- Remote path: /path/to/your/project

Debugging workflow:

Start the agent with --debug flag (agent listens on port 5678)
Set breakpoints in your Python files (click in the left margin)
Select "AgentVisor: Attach (DAP)" from toolbar dropdown
Click the debug button (green bug icon) or press Shift+F9
Debug using F8 (step over), F7 (step into), F9 (resume)

Option B: Native Debugger (pydevd)

The pydevd provider offers tighter PyCharm integration with Cython-optimized evaluation and better Django/Flask debugging. The connection direction is the same as debugpy above — the agent listens first, then PyCharm connects — but pydevd uses its own native wire protocol instead of DAP.

Install pydevd-pycharm in your virtual environment:

pip install pydevd-pycharm

Configure PyCharm:

Open Run → Edit Configurations...
Click + → Python Debug Server
Configure:
- Name: AgentVisor: pydevd
- IDE host name: localhost
- Port: 5678
Add Path mappings:
- Local path: /path/to/your/agent-project
- Remote path: /path/to/your/agent-project

Path Mappings

Since you're running in --sandbox=none mode, local and remote paths are typically identical.

Debugging workflow:

Start the agent first — it starts a pydevd server and listens on the debug port:

agentvisor run ./my-agent \
    --sandbox=none \
    --debug \
    --debug-provider=pydevd \
    --input '{"messages": [{"role": "user", "content": "Hello"}]}'

Set breakpoints in your Python files
Select "AgentVisor: pydevd" from the toolbar dropdown and click the Debug button (green bug icon) or press Shift+F9 — PyCharm connects to the agent's listening pydevd server
Debug using F8 (step over), F7 (step into), Shift+F8 (step out), F9 (resume)

pydevd Never Waits

Unlike debugpy, pydevd's server mode does not block execution while waiting for a debugger to attach — the agent starts running as soon as the port opens. There is no provider option to change this (--debug-opt is a generic mechanism for passing key=value pairs to a provider, but the pydevd provider currently doesn't read any). Attach promptly, or use debugpy (Option A) if you need the agent to pause until you connect.

Troubleshooting

Connection refused:

For debugpy and pydevd alike: the agent is the one listening — start it with --debug (and --debug-provider=pydevd for pydevd) before trying to connect from your IDE, and ensure ports match

Breakpoints not hitting:

Verify path mappings in your debug configuration match your project structure
For --sandbox=none, local and remote paths should be identical

Port already in use:

Use --debug-port with a different port
Update your IDE configuration to match

Module 'debugpy' not found:

pip install debugpy

Module 'pydevd' not found:

pip install pydevd-pycharm

Agent doesn't wait for debugger (pydevd):

This is expected — pydevd's server mode never blocks waiting for a client, unlike debugpy's --wait-for-client. Attach quickly after starting the agent, or switch to debugpy (Option A) if you need the agent to pause.

Troubleshooting

"ModuleNotFoundError: No module named 'agentvisor'"

Your virtual environment isn't activated or the SDK isn't installed. Activate the venv and re-install the SDK from the release wheel — see SDK Installation above:

source .venv/bin/activate
pip install "${WHEEL}[langgraph]"

"ModuleNotFoundError: No module named 'langchain_ollama'"

Your agent's dependencies aren't installed:

pip install -r requirements.txt

Agent runs but can't connect to services

Make sure Temporal and any other services are running:

docker compose up -d

Different behavior between unsandboxed and container modes

Running without sandbox isolation uses your local Python environment, which may have different package versions than the container. To match container behavior exactly:

# Check what's in the container (use -python or -minimal depending on your agent type)
# --entrypoint overrides the image's default entrypoint (the guest runtime binary)
docker run --rm --entrypoint pip ghcr.io/manetu/agentvisor/agentvisor-guest:latest-python list

# Install matching versions in your venv
pip install langchain==<version> langgraph==<version>

When to Use Each Mode

Mode	Use Case
`--sandbox=none`	Debugging, breakpoints, fast iteration (no isolation)
`--sandbox=docker`	Default; production-grade containment on any platform
`--sandbox=gvisor`	Strongest isolation (Linux only); recommended for Linux production

Next Steps

Agent Logging: Structured logging for debugging
Sandbox Modes: Understanding isolation levels
Environment Configuration: Managing secrets and config

Why Disable the Sandbox?​

Prerequisites​

Setup Steps​

1. Create a Virtual Environment​

2. SDK Installation​

Installation Variants​

When You Need Manual Installation​

When You Don't Need Manual Installation​

requirements.txt and the SDK​

3. Verify Installation​

Running with the Sandbox Disabled​

Complete Example​

Interactive Debugging​

Choosing a Debug Provider​

Using Debug Mode​

VS Code Setup​

PyCharm Setup​

Option A: Debug Adapter Protocol (debugpy)​

Option B: Native Debugger (pydevd)​

Troubleshooting​

Troubleshooting​

"ModuleNotFoundError: No module named 'agentvisor'"​

"ModuleNotFoundError: No module named 'langchain_ollama'"​

Agent runs but can't connect to services​

Different behavior between unsandboxed and container modes​

When to Use Each Mode​

Next Steps​

Why Disable the Sandbox?

Prerequisites

Setup Steps

1. Create a Virtual Environment

2. SDK Installation

Installation Variants

When You Need Manual Installation

When You Don't Need Manual Installation

requirements.txt and the SDK

3. Verify Installation

Running with the Sandbox Disabled

Complete Example

Interactive Debugging

Choosing a Debug Provider

Using Debug Mode

VS Code Setup

PyCharm Setup

Option A: Debug Adapter Protocol (debugpy)

Option B: Native Debugger (pydevd)

Troubleshooting

Troubleshooting

"ModuleNotFoundError: No module named 'agentvisor'"

"ModuleNotFoundError: No module named 'langchain_ollama'"

Agent runs but can't connect to services

Different behavior between unsandboxed and container modes

When to Use Each Mode

Next Steps