Skip to main content
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.

​
Choose a workspace

agent.ts
Here, base.ts is the normal invoice agent from the quickstart. 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.
  • 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

packages.ts
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.