Skip to main content

Simple Shell

An interactive /bin/sh shell running inside the AgentVisor™ sandbox via agentvisor exec — the simplest possible interactive session. Network policy is still enforced even though nothing in this example calls an LLM or brokers a credential.

Difficulty: Expert

info

This example demonstrates agentvisor exec mode. Unlike serve and run, exec mode bridges your terminal directly into the sandbox without Temporal workflows or an HTTP API. All HTTP proxy, MCP, A2A, and store features remain available.

What You'll Learn​

  • Using agentvisor exec for interactive terminal sessions
  • The minimum mav-agent-config.yaml needed to select the interactive framework provider
  • That the sandbox's HTTP policy is enforced independently of what's running inside — even a plain shell can only reach what the policy allows
  • Providing a custom Dockerfile to add tools to the minimal guest image
  • Which downcalls are and aren't available in exec mode

Security Model​

The sandbox enforces the same defense-in-depth as serve mode:

  • HTTP proxy: All outbound HTTP/HTTPS goes through the policy engine — this example's policy allows only Ollama endpoints, denying everything else by default
  • Network isolation: No direct outbound connections (all traffic via proxy)
  • Syscall filtering: gVisor's application kernel (when --sandbox=gvisor)

Unlike Claude Code, this example ships no credential brokering — it's the minimum viable interactive provider configuration, useful as a starting point for your own command.

Project Structure​

simple-shell/
├── mav-agent-config.yaml   # Framework config: interactive provider + command
├── Dockerfile               # Adds shell/network tools to the guest image
└── policies/
    ├── domain.yml            # MPE PolicyDomain — Ollama HTTP access only
    └── test.yml               # Policy test cases

mav-agent-config.yaml​

framework:
  provider: interactive
  command: ["/bin/sh", "-l"]
  env:
    TERM: xterm-256color

Change command to run any interactive tool — a Python REPL, bash, aider, etc. provider: interactive is required; it's what selects the PTY-based framework provider instead of LangGraph/CrewAI/ADK discovery.

policies/domain.yml (highlights)​

The policy allows only Ollama HTTP endpoints; every other resource group defaults to deny:

# Extract target from MRN (mrn:agentvisor:http:host/path -> host/path)
http_target := substring(input.resource.id, count("mrn:agentvisor:http:"), -1)

# Allow Ollama endpoints
allow if {
    helpers.is_authenticated
    regex.match("^ollama(:\\d+)?(/.*)?$", http_target)
}

# Also allow localhost:11434 / 127.0.0.1:11434 for --sandbox=none

There's no credential brokering here — this is a policy-enforced shell, not a credentialed AI tool. See Claude Code for an example that layers credential substitution on top of the same interactive provider.

Setup​

agentvisor template create interactive/simple-shell
cd simple-shell

No API keys, Temporal, or Ollama are required to start a session — network policy is enforced regardless of whether anything actually calls Ollama.

Run​

Direct exec (development)​

# Drops you into `/bin/sh -l` inside the sandbox
agentvisor exec .

# Or specify a different command inline
agentvisor exec . --command "bash"

# With gVisor isolation (Linux only)
agentvisor exec . --sandbox=gvisor

For local debugging without a sandbox:

agentvisor exec . --sandbox=none

Exit normally (exit or Ctrl-D) to end the session.

Build and run interactively (production)​

# Build the OCI image (embeds the shell environment and policies)
agentvisor build . -t simple-shell:latest

# Run interactively with Docker + gVisor
docker run -it --rm \
    --security-opt seccomp=unconfined \
    --security-opt apparmor=unconfined \
    -e AGENTVISOR_AUTHZ_TYPE=embedded \
    -e AGENTVISOR_AUTHZ_EMBEDDED_POLICY_DOMAIN_FILES=/agent/policies/domain.yml \
    simple-shell:latest \
    exec /agent

Logging​

By default, exec mode is silent — no logs appear on the terminal, keeping the interactive session clean. To debug issues:

# Write logs to a file (terminal stays clean)
agentvisor exec . --log-file /tmp/agentvisor.log

# Print logs to stderr
agentvisor exec . --verbose

Available Downcalls​

FeatureAvailable
HTTP proxy (with credential substitution)Yes
MCP gatewayYes
A2A gatewayYes
Key-value storeYes
Log forwardingYes
CheckpointingNo
SSE streamingNo

Checkpointing and SSE streaming require Temporal workflows and the HTTP API, which exec mode intentionally omits.

Coding Agent with Project Access​

Use --mount to give the shell read-write access to your project files. Changes made inside the sandbox are written directly to the host path.

# Drop into a writable shell with your project mounted
agentvisor exec . --mount $PWD:/work:rw:cwd

# Inside the sandbox:
# $ pwd        → /work
# $ ls         → your project files
# $ touch new-file.txt  → visible on host after exit

The :cwd token sets /work as the working directory when the session starts, so the shell lands directly inside your project.

Read-Only vs Read-Write​

ModeFlagWhen to Use
Read-only (ro)--mount $PWD:/work:ro:cwdInspection, analysis, or review — the shell cannot accidentally modify your files
Read-write (rw)--mount $PWD:/work:rw:cwdActive development — the shell can create, edit, and delete files
caution

Read-write mounts give the sandboxed shell direct access to a subtree of your host filesystem. HTTP access is still gated by the policy engine, but filesystem writes are not. Use a minimal host path rather than mounting $HOME or /.

Multiple Mounts​

Combine a writable workspace with read-only reference data:

agentvisor exec . \
  --mount $PWD:/work:rw:cwd \
  --mount ~/datasets:/data:ro

The shell can read from /data but cannot modify it, while /work is fully writable.

Customizing the Environment​

To install additional tools or packages into the sandbox, place a Dockerfile in the agent source directory (next to mav-agent-config.yaml). It overrides the embedded minimal template and is processed at build time:

FROM {{.Image}}

# The base image is ubi9/ubi-minimal — use microdnf, not apt-get.
RUN microdnf install -y \
      wget \
      git \
      procps-ng \
      iputils \
      net-tools \
      lsof \
      bind-utils \
      nftables \
     && microdnf clean all

COPY agent /app/agent

{{.Image}} resolves to the correct versioned base image. Other available template variables: {{.ImageRepo}}, {{.ImageVersion}}, {{.ImageVariant}}, {{.HasRequirements}}. See exec reference — Customizing the Sandbox Environment for the full list.

See Also​