# Filesystem

Canonical: https://auggy.dev/docs/augment-filesystem
Status: Published
Package: auggy 0.5.0

Expose named operator-controlled host paths for file reads, writes, search, and workspace reuse.

## Give the agent a durable workspace

**What it enables:** Let the agent read installed skills and create, revise, find, or remove artifacts in an operator-selected workspace.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `6 tools`, `workspace context`, `admin summary`

The model addresses logical paths such as `workspace/reports/q3.md`; the augment maps the first segment to the host path selected by the operator. The default workspace catalog injects bounded filename and metadata hints for creator and agent turns so existing artifacts can be reused without loading file contents automatically.

## Generated install

``auggy create <name>`` adds `filesystem` to `agent.yaml`, creates `<agent>/data/workspace/README.md`, copies the bundled skill to `<agent>/skills/filesystem/`, and writes this file at `<agent>/augments/filesystem/augment.yaml`.

**augments/filesystem/augment.yaml**

```yaml
type: filesystem
config:
  mounts:
    - name: skills
      path: ./skills
      writable: false
    - name: workspace
      path: ./data/workspace
      writable: true
      deletable: true
  workspaceAwareness:
    enabled: true
    maxEntries: 24
    maxDepth: 4
```

Relative mount paths resolve from the agent directory. Add only paths the operator intends the **Auggy** process and model-selected tools to access.

## Write a reusable report

A creator can ask the agent to preserve a report for later work. The model can write it directly to the generated workspace:

**Model tool call**

```
fs_write({
  path: "workspace/reports/weekly.md",
  content: "# Weekly report\n\n- Launch checks passed\n- Follow up on billing alerts\n"
})
```

Parent directories are created automatically. A later turn can find the artifact with ``fs_search`({ path: "workspace", pattern: "**/*.md" })` and read it with ``fs_read``.

## Runtime surfaces

| Surface | Input and behavior |
| --- | --- |
| ``fs_read`` | `{ path }`; reads text, rejects known binary extensions, and truncates at 256 KiB by default. |
| ``fs_list`` | `{ path }`; returns JSON metadata for one file or a directory listing. |
| ``fs_write`` | `{ path, content }`; creates parent directories and writes up to 1 MiB by default. |
| ``fs_mkdir`` | `{ path }`; recursively creates a directory in a writable mount. |
| ``fs_remove`` | `{ path }`; removes a file or empty directory only when the mount is writable and deletable. |
| ``fs_search`` | `{ path, pattern, maxResults? }`; glob search, default 100 results, hard cap 1000. |
| Workspace context | Per-turn policy plus at most 24 catalog paths to depth 4 for creator and agent trust by default; no file contents. |

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | Public turns can see read/list/search tools but not write, mkdir, or remove. Agent-trust turns can write and mkdir but cannot remove. Creator turns still obey each mount's writable and deletable flags. |
| Persistence | Files are ordinary host files. `data/` is gitignored; local persistence lasts until the operator or a permitted tool removes the data. |
| Deployment | **Railway** excludes local `data/` contents from the image, then mounts persistent storage at `/app/data`. New cloud workspace writes persist there, but local workspace files are not uploaded by ``auggy deploy``. |
| Limits | Known binary types are not readable, non-empty directories cannot be removed, search excludes `.git`, ``node_modules``, `.next`, `__pycache__`, and `.DS_Store` by default, and the augment caps filesystem tool calls at 15 per turn. |

> **Warning: Host access, not a sandbox**
>
> A mount grants access to an operator-controlled host path using the **Auggy** process user's permissions. Mount names and per-operation flags narrow the tool API; they are not a container, sandbox, privilege boundary, or general confinement guarantee. Do not mount secrets, credentials, or broad host directories unless that access is intentional.

## Verify

**Inspect the generated workspace**

```bash
cd <agent>
auggy run
# In another terminal after the write:
test -f data/workspace/reports/weekly.md
cat data/workspace/reports/weekly.md
```

1. Confirm ``/console/capabilities`` lists the `skills` read-only mount and writable, deletable `workspace` mount.
2. Ask the agent to create the weekly report and inspect the ``fs_write`` result.
3. Confirm the file exists under `data/workspace/reports/weekly.md` with the expected content.
4. In a later turn, ask for existing Markdown reports and confirm ``fs_search`` finds the same logical path.
5. From an anonymous turn, confirm mutation tools are absent even though read-only filesystem tools remain available.

## Related

- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [File Memory](https://auggy.dev/docs/augment-file-memory/markdown)