anvillm-mcp/docs/code-execution-user-guide.md

Code Execution User Guide

Overview

execute_code is the only MCP tool provided by anvilmcp. It runs bash scripts in an isolated subprocess sandboxed via landrun. All AnviLLM functionality is accessed through 9P and helper scripts within these subprocesses.

Tool Discovery

List available helper scripts:

9p ls anvillm/tools/

Read a script to see its usage:

9p read anvillm/tools/check_inbox.sh

Invoke a script:

bash <(9p read anvillm/tools/check_inbox.sh)

Common Patterns

Messaging

# Check inbox
bash <(9p read anvillm/tools/check_inbox.sh)

# Send message
bash <(9p read anvillm/tools/send_message.sh) \
  --to user --type PROMPT_RESPONSE --subject "Done" --body "Complete"

Session Management

9p read anvillm/list
9p read anvillm/$ID/state

Beads

9p read anvillm/beads/list | jq '[.[] | select(.status == "open")]'
echo 'new "Task title" "Task description"' | 9p write anvillm/beads/ctl

Polling

while true; do
  state=$(9p read anvillm/$ID/state)
  [ "$state" = "idle" ] && break
  sleep 5
done

Filtering

Process data in the subprocess — only return summaries to the agent:

beads=$(9p read anvillm/beads/list)
count=$(echo "$beads" | jq '[.[] | select(.priority <= 2)] | length')
echo "Found $count high-priority beads"

Subprocess Restrictions

Scripts run in a landrun sandbox with limited permissions:

• Read/write to the session's working directory
• Read from system paths (/usr, /lib, /bin)
• Access to 9P namespace
• Standard utilities: jq, grep, sed, awk, 9p
• Network access per sandbox config

Error Handling

if output=$(9p read anvillm/beads/list 2>&1); then
  echo "$output" | jq 'length'
else
  echo "Failed: $output" >&2
  exit 1
fi

Further Reading

• Code Execution Pattern — design rationale
• Security Documentation — threat model and sandbox config
• Example Workflows — common patterns