Workspace Files

Workspace files give agents durable file-style storage for notes, scratchpads, logs, todos, task progress, generated code, and research files.

The workspace has two clear areas:

files/ — agent-managed files for scratchpads, todos, progress, preferences, notes, subagent outputs, and generated work.
artifacts/ — runtime-managed tool output artifacts created by tool offloading and read back with artifact tools.

There is no separate workspace-files backend: choose the workspace backend once, and both areas use that same local, S3, or R2 workspace.

Workspace Backends

Backend	Use Case	Benefits
`local`	Development, single-server	Zero config, instant setup
`s3`	Production, AWS infrastructure	Scalable, durable, global access
`r2`	Production, edge computing	Zero egress fees, Cloudflare ecosystem

Quick Setup

Workspace files default to local disk. Choose S3 or R2 only when the whole workspace should live in cloud storage.

export OMNICOREAGENT_WORKSPACE_BACKEND=local
export OMNICOREAGENT_WORKSPACE_DIR=./workspace

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="workspace_agent",
        system_instruction=(
            "Use workspace files for notes, progress, and final artifacts."
        ),
        model_config={"provider": "openai", "model": "gpt-4o"},
        agent_config={"enable_workspace_files": True},
    )

    result = await agent.run(
        "Create a project note at notes/plan.md with three checklist items, "
        "then read it back."
    )
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

With the local backend, workspace command tools write under:

./workspace/files/

For example, the prompt above creates ./workspace/files/notes/plan.md. Cloud workspace storage uses the S3/R2 extra:

pip install "omnicoreagent[s3]"

Environment Variables

Local

OMNICOREAGENT_WORKSPACE_BACKEND=local
OMNICOREAGENT_WORKSPACE_DIR=./workspace

S3

OMNICOREAGENT_WORKSPACE_BACKEND=s3
OMNICOREAGENT_WORKSPACE_PREFIX=workspace
AWS_S3_BUCKET=my-agent-workspace
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1  # optional

R2

OMNICOREAGENT_WORKSPACE_BACKEND=r2
OMNICOREAGENT_WORKSPACE_PREFIX=workspace
R2_BUCKET_NAME=my-agent-workspace
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-key
R2_SECRET_ACCESS_KEY=your-r2-secret

Workspace Command Tools

OmniCoreAgent exposes these tools for the files/ area:

Tool	Purpose
`ls`	List files and directories
`read_file`	Read file contents, like workspace-scoped `cat`
`write_file`	Create, append, or overwrite files
`edit_file`	Find and replace text within files
`insert_file`	Insert text at specific line numbers
`delete_file`	Delete files or directories
`move_file`	Rename or move files
`clear_files`	Clear the workspace files area
`glob`	Find files by glob pattern
`grep`	Search text inside workspace files

These are workspace tools, not host shell tools. They operate through the active workspace backend, so the same tool calls work on local disk, S3, and R2. When workspace files are enabled, these tool names are reserved for the harness. Use distinct names for application-owned local tools.

Backend Behavior

Feature	Local	S3	R2
Persists across process restarts	Yes	Yes	Yes
Works without cloud credentials	Yes	No	No
Shared across multiple machines	No	Yes	Yes
Fits single-server development	Yes	Yes	Yes
Fits distributed deployments	Limited	Yes	Yes
Uses the same workspace tools	Yes	Yes	Yes

Use Cases

Use Case	Recommended Backend
Local development	`local`
Single-server production	`local` or `s3`
Multi-server / Kubernetes	`s3` or `r2`
Edge computing / Workers	`r2`
Cost-sensitive workloads	`r2` (zero egress)

Example: Research Agent with Cloud Workspace

import os

# Set environment for S3
os.environ["OMNICOREAGENT_WORKSPACE_BACKEND"] = "s3"
os.environ["AWS_S3_BUCKET"] = "research-agent-workspace"
os.environ["AWS_ACCESS_KEY_ID"] = "AKIA..."
os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
os.environ["AWS_REGION"] = "us-east-1"
os.environ["AWS_ENDPOINT_URL"] = "https://s3.amazonaws.com"  # Optional

agent = OmniCoreAgent(
    name="workspace_agent",
    system_instruction="Save durable notes, logs, task progress, and final output to workspace files.",
    model_config={"provider": "openai", "model": "gpt-4o"},
    agent_config={
        "max_steps": 50,
    }
)

# Agent can now save research notes that persist across:
# - Server restarts
# - Multiple instances
# - Different geographic locations
result = await agent.run(
    "Research recent AI developments and save a summary to /notes/ai_trends.md"
)

Use local for development. Use s3 or r2 when the whole workspace should persist across server restarts, multiple agent instances, or production deployments.

Get Started

Core Concepts

How-To Guides

Changelog

Workspace Files

Workspace Files

Workspace Backends

Quick Setup

Environment Variables

Local

S3

R2

Workspace Command Tools

Backend Behavior

Use Cases

Example: Research Agent with Cloud Workspace

​Workspace Files

​Workspace Backends

​Quick Setup

​Environment Variables

​Local

​S3

​R2

​Workspace Command Tools

​Backend Behavior

​Use Cases

​Example: Research Agent with Cloud Workspace

Workspace Files

Workspace Backends

Quick Setup

Environment Variables

Local

S3

R2

Workspace Command Tools

Backend Behavior

Use Cases

Example: Research Agent with Cloud Workspace