Shared Compute Sandbox

Give every agent in a team or workflow one shared /workspace so a file written by step 1 is visible to step 2. Without a shared sandbox, each agent provisions its own isolated instance, so agents cannot hand files to each other. Set compute= once on the flow or team and every agent shares the same filesystem.

Quick Start

Simplest Usage (AgentFlow)

Set compute="docker" on the flow — every step runs its shell and file tools in one sandbox.

from praisonaiagents import Agent, AgentFlow

writer = Agent(name="Writer", instructions="Write files")
reader = Agent(name="Reader", instructions="Read files")

flow = AgentFlow(compute="docker", steps=[writer, reader])
flow.run("Step 1: write 'SECRET-42' to /workspace/data.txt. Step 2: read it back.")

AgentTeam

The same compute= kwarg works on a team.

from praisonaiagents import Agent, Task, AgentTeam

writer = Agent(name="Writer", instructions="Write files")
reader = Agent(name="Reader", instructions="Read files")

team = AgentTeam(
    agents=[writer, reader],
    tasks=[
        Task(description="Write 'SECRET-42' to /workspace/data.txt", agent=writer),
        Task(description="Read /workspace/data.txt and report it", agent=reader),
    ],
    compute="docker",
)
team.start()

Pick a Provider

Pass a provider name, or a pre-configured instance for custom image and resources.

flow = AgentFlow(compute="docker", steps=[writer, reader])

flow = AgentFlow(compute="e2b", steps=[writer, reader])

flow = AgentFlow(compute="daytona", steps=[writer, reader])

flow = AgentFlow(compute="flyio", steps=[writer, reader])

flow = AgentFlow(compute="tenki", steps=[writer, reader])

flow = AgentFlow(compute="local", steps=[writer, reader])

from praisonai.integrations.compute.docker import DockerCompute

flow = AgentFlow(
    compute=DockerCompute(image="python:3.12-slim", cpu=2, memory_gb=4),
    steps=[writer, reader],
)

How It Works

The sandbox is provisioned lazily on first tool use and torn down when the run ends.

Behaviour	What actually happens
Lazy	Nothing is provisioned until the first tool call. A run that never touches the sandbox costs nothing.
Single instance	Concurrent first-use calls from parallel branches share one sandbox, not several — provisioning is guarded by a lock with double-checked locking.
Safe file writes	Any content is written verbatim, including bodies that contain heredoc-terminator-looking text — every `write_file` uses a fresh randomised delimiter, so file content can never terminate the write early or leak into the shell.
Shared filesystem	Every attached agent’s `/workspace` is the same directory in the same instance.
Guaranteed teardown	The instance is released on exit even if a step raises. Agents are restored to their original tools and backstory.
Backend-owning agents skipped	Agents that already carry their own `backend=` are left alone.
Same-name tool replacement	Local `execute_command` / `read_file` / `write_file` / `list_files` are replaced; unrelated tools are kept.
Empty result guard	A silent-but-successful command returns `"(command succeeded with no output)"` so the loop guard never reports no progress.

Configuration Options

Set compute= on AgentFlow (or its Workflow / Pipeline aliases) or on AgentTeam. Orchestration (route, parallel, repeat, when) stays local — only shell and file tools follow the sandbox.

Value	Meaning
`None` (default)	No shared sandbox. Existing per-agent behaviour is unchanged.
`"local"`	Run inside a local subprocess (no isolation). Useful for tests.
`"docker"`	Local Docker container. Requires Docker running.
`"e2b"`	E2B cloud sandbox. Requires `E2B_API_KEY` and `pip install praisonai[e2b]`.
`"modal"`	Modal cloud compute. Requires `MODAL_TOKEN` and `pip install praisonai[modal]`.
`"daytona"`	Daytona workspace. Requires `pip install praisonai[daytona]`.
`"flyio"`	Fly.io machine.
`"tenki"`	Tenki Cloud microVM. Requires `TENKI_API_KEY`.
Provider instance	Any object implementing `ComputeProviderProtocol` (`provision`, `execute`, `shutdown`). Use this to customise image, CPU, memory, env, or working dir.

Any other string raises ValueError.

AgentFlow API Reference

The workflow orchestrator that accepts compute=.

Common Patterns

Hand a file between two agents — step 1 writes, step 2 reads the same /workspace.

from praisonaiagents import Agent, AgentFlow

writer = Agent(name="Writer", instructions="Write files")
reader = Agent(name="Reader", instructions="Read files")

flow = AgentFlow(compute="docker", steps=[writer, reader])
flow.run("Step 1: write /workspace/data.txt. Step 2: read it back.")

Run one shared sandbox across a parallel fan-out — three branches, one sandbox.

from praisonaiagents import Agent, AgentFlow, parallel

a = Agent(name="A", instructions="Work on /workspace")
b = Agent(name="B", instructions="Work on /workspace")
c = Agent(name="C", instructions="Work on /workspace")

flow = AgentFlow(compute="docker", steps=[parallel([a, b, c])])
flow.run("Each branch appends a line to /workspace/log.txt")

Agents inside nested containers — route, repeat, when, loop, if — all bind to the same sandbox automatically.

from praisonaiagents import Agent, AgentFlow, parallel, repeat, when

writer = Agent(name="Writer", instructions="Write to /workspace")
reader = Agent(name="Reader", instructions="Read from /workspace")

flow = AgentFlow(
    compute="docker",
    steps=[
        writer,
        parallel([writer, reader]),
        when("{{ready}}", [reader], [writer]),
        repeat(reader, until=lambda ctx: ctx.get("done")),
    ],
)
flow.run("Coordinate writer and reader through /workspace")

Each agent is attached exactly once, even if it appears in multiple containers. Custom image or resources — pass a pre-configured provider instance.

from praisonaiagents import Agent, AgentFlow
from praisonai.integrations.compute.docker import DockerCompute

writer = Agent(name="Writer", instructions="Write files")
reader = Agent(name="Reader", instructions="Read files")

flow = AgentFlow(
    compute=DockerCompute(image="python:3.12-slim", cpu=2, memory_gb=4),
    steps=[writer, reader],
)
flow.run("Build and test in /workspace")

Best Practices

Leave compute=None unless you need shared execution

The default is zero-overhead — nothing is provisioned. Only set compute= when a run actually shares files or shell state across agents.

Give the sandbox enough resources for the biggest step

All steps share the same instance. Size the image, CPU, and memory for the heaviest step, since it affects the whole run.

Don't mix compute= with agents that carry their own backend=

Backend-owning agents are deliberately skipped by the shared sandbox — they keep pointing at their own runtime. Use one approach or the other per agent.

Write any content with write_file — no escaping needed

Every call to write_file uses a fresh random heredoc delimiter, so file bodies containing quotes, heredoc terminators, or shell fragments are written verbatim and never leak into the shell. You do not need to escape, quote, or sanitise content yourself.

Local Agent

Per-agent compute — one agent’s tools in a sandbox.

Sandboxed Agent

Per-agent compute — isolate a single agent’s tools.

AgentFlow

The workflow orchestrator.

AgentTeam

The team orchestrator.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Shared Compute Sandbox

Quick Start

How It Works

Configuration Options

AgentFlow API Reference

Common Patterns

Best Practices

Local Agent

Sandboxed Agent

AgentFlow

AgentTeam

​Quick Start

​How It Works

​Configuration Options

AgentFlow API Reference

​Common Patterns

​Best Practices

​Related

Local Agent

Sandboxed Agent

AgentFlow

AgentTeam

Quick Start

How It Works

Configuration Options

Common Patterns

Best Practices

Related