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

# Add filesystem access to agents

> Give an EigenPal agent an optional sandbox with a repository or empty workspace, seed files, imported skills, and exact Python or npm package versions.

Add `.withFilesystem()` when your agent needs file operations, shell scripts or
installed libraries. The agent keeps its existing tools, schemas, resources,
evaluators and pass rule. Its custom TypeScript callbacks keep the
[same QuickJS permissions](/sdks/automations/callbacks).

## Choose a workspace

```ts agent.ts theme={null}
import reviewer from './base.ts';

export default reviewer.withFilesystem({
  cwd: null,
  files: { 'invoice.txt': 'Subtotal: 100; tax rate: 0.2' },
});
```

Here, `base.ts` is the normal invoice agent from the [quickstart](/sdks/automations).
The new definition starts empty, adds `invoice.txt` and leaves `reviewer` unchanged.

Choose `cwd` to control initial workspace content:

* **Omit `cwd`**, or call `.withFilesystem()` without arguments, to check out the
  pinned repository commit and start in the agent's package directory.
* **Set a string** such as `'agents/invoice-reviewer'` to select an existing
  repository-relative directory. `'.'` selects the repository root.
* **Set `null`** to skip the execution checkout. The working directory starts with
  seed files and explicitly attached resources/skills. Instructions still come
  from the pinned definition or `AGENT.md`.

An empty string is invalid. Paths must remain inside the checkout after symlink
resolution. `cwd` chooses the initial directory; it does not restrict which paths
the agent's sandbox tools can access.

## Filesystem options

* **`cwd?: string | null`**: initial directory/content selection, described above.
* **`files?: Record<string, string>`**: UTF-8 seed content relative to `cwd`.
  Missing directories are created. Identical existing files are accepted; differing
  files fail setup instead of being overwritten. Seed content does not commit to Git.
* **`skills?`**: aliases mapped to imported `createSkill` declarations. Skills keep
  their `SKILL.md` and companion files; see [Resources](/sdks/automations/resources).
* **`packages.python?`**: Python package names mapped to exact versions.
* **`packages.npm?`**: npm package names mapped to exact versions.

Paths use ASCII letters, digits, `_`, `.`, `-` and `/`. Traversal, absolute paths,
symlinks and managed directories such as `.git`, `.eigenpal`, `node_modules` and
`eigenpal_modules` are rejected. Spaces and Unicode names are unsupported in these
workspace paths. Seed files allow at most 100 entries and 256 KiB total paths/content.
Use Git assets or run input files for binary content.

## Install sandbox libraries

```ts packages.ts theme={null}
import reviewer from './base.ts';

export default reviewer.withFilesystem({
  packages: {
    python: { openpyxl: '3.1.5', numpy: '2.3.3' },
    npm: { 'decimal.js': '10.6.0' },
  },
});
```

The runtime installs these packages inside the sandbox. Python packages combine
with `requirements.txt` in the selected directory; npm packages combine with its
`package.json`. Conflicting declared versions fail setup before model execution.
Existing repository manifests also work without extra `packages` settings.

Use at most 32 additional packages across both maps. Python accepts numeric release
versions with two to four components; npm accepts exact three-component versions
and prereleases. Ranges, URLs, alternate indexes and install flags are unsupported.
Direct versions are pinned; these settings do not guarantee a fully locked
transitive dependency tree. Existing `bun.lock` is reused by the installer.

There is no language setting. The agent can use shell tools to run Python and
JavaScript in one sandbox. Installing `decimal.js` does not make an import from
that package valid inside `createTool.execute` or an evaluation callback.

## Resources and repeated calls

Attached resources stay under `/workspace/agent/.eigenpal-resources/<alias>/`,
independent of `cwd`. `cwd: null` still installs them alongside seed files.
Resources do not merge into or overwrite seed files.

Calling `.withFilesystem()` again replaces its previous filesystem settings,
including seed files, packages and skills; it does not merge them. The base
agent's portable resources stay attached. Each call returns a new definition.

## Deployments without sandboxes

Normal agents remain available. A filesystem run fails with
`agent_capability_unavailable` before model execution or sandbox provisioning if
the deployment lacks an enabled provider. EigenPal does not silently run it
without filesystem capabilities. Ask the deployment operator to enable a provider,
or author a normal agent that uses structured inputs and portable resources.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.