> ## Documentation Index
> Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Files

> Persistent workspace files inside the active local, S3, or R2 workspace

# 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OMNICOREAGENT_WORKSPACE_BACKEND=local
export OMNICOREAGENT_WORKSPACE_DIR=./workspace
```

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
./workspace/files/
```

For example, the prompt above creates `./workspace/files/notes/plan.md`.

Cloud workspace storage uses the S3/R2 extra:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "omnicoreagent[s3]"
```

***

## Environment Variables

### Local

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OMNICOREAGENT_WORKSPACE_BACKEND=local
OMNICOREAGENT_WORKSPACE_DIR=./workspace
```

### S3

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
)
```

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