Skip to main content

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:

  1. Python 3.10 or later
  2. A Python virtual environment
  3. 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]"
ExtraAdds
(none)Core features (checkpointing, logging, store, MCP)
langgraphLangGraph checkpointer, graph discovery
langchainLangChain MCP tool integration
crewaiCrewAI crew discovery, MCP tools adapter
adkGoogle ADK agent discovery, session adapter
strandsStrands Agents runner, schema registration, MCP tools adapter
tracingOpenTelemetry tracing helpers
allAll 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:

  1. Create a venv with the AgentVisor SDK installed
  2. 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​

ProviderProtocolBest ForInstall
debugpy (default)DAPVS Code, any DAP clientpip install debugpy
pydevdpydevdPyCharm native featurespip 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:

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

PyCharm Setup​

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

ApproachConnection ModelAdvantages
Option A: DAP (debugpy)Agent listens, IDE connectsStandard 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:

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

Debugging workflow:

  1. Start the agent with --debug flag (agent listens on port 5678)
  2. Set breakpoints in your Python files (click in the left margin)
  3. Select "AgentVisor: Attach (DAP)" from toolbar dropdown
  4. Click the debug button (green bug icon) or press Shift+F9
  5. 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:

  1. Open Run → Edit Configurations...
  2. Click + → Python Debug Server
  3. Configure:
    • Name: AgentVisor: pydevd
    • IDE host name: localhost
    • Port: 5678
  4. 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:

  1. 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"}]}'
  2. Set breakpoints in your Python files
  3. 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
  4. 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

See Troubleshooting Guide: Temporal Connectivity if Temporal itself is unreachable.

If the target is a local service such as Ollama and the connection fails with a 400 or an empty 502 instead of a connection error, the outbound proxy's SSRF guard is involved — see Troubleshooting Guide: Outbound Destination Blocked and Egress Controls.

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​

ModeUse Case
--sandbox=noneDebugging, breakpoints, fast iteration (no isolation)
--sandbox=dockerDefault; production-grade isolation on any platform
--sandbox=gvisorStrongest isolation (Linux only); recommended for Linux production

Next Steps​