Skip to main content
Complete reference for the agentfs command-line tool.
For the latest reference, see MANUAL.md in the repository.

​
Installation

curl -fsSL https://github.com/tursodatabase/agentfs/releases/latest/download/agentfs-installer.sh | sh

​
Commands

​
agentfs init

Initialize a new agent filesystem. 
agentfs init [OPTIONS] [ID]
Arguments:
  • ID - Agent identifier (default: agent-{timestamp})
Options:
OptionDescription
--forceOverwrite existing agent filesystem
--base <PATH>Base directory for overlay filesystem
--sync-remote-url <URL>Remote Turso database URL
Example: 
agentfs init my-agent
agentfs init my-overlay --base /path/to/project

​
agentfs run

Execute a program in a sandboxed environment. 
agentfs run [OPTIONS] <COMMAND> [ARGS]...
Options:
OptionDescription
--session <ID>Named session for persistence
--allow <PATH>Allow write access to directory
--no-default-allowsDisable default allowed directories
--experimental-sandboxUse ptrace sandbox (Linux)
--straceShow intercepted syscalls
Examples: 
agentfs run /bin/bash
agentfs run --session my-project python3 agent.py
agentfs run --allow /tmp --allow ~/.cache /bin/bash

​
agentfs mount

Mount an agent filesystem or list mounts. 
agentfs mount [OPTIONS] [ID_OR_PATH] [MOUNT_POINT]
Without arguments, lists all mounted filesystems. Options:
OptionDescription
-a, --auto-unmountAutomatically unmount on exit
--allow-rootAllow root user access
-f, --foregroundRun in foreground
--uid <UID>User ID for files
--gid <GID>Group ID for files
Examples: 
agentfs mount                              # List mounts
agentfs mount my-agent ./mnt               # Mount agent
agentfs mount my-agent ./mnt -a -f         # Foreground with auto-unmount
Unmounting:
  • Linux: fusermount -u <MOUNT_POINT>
  • macOS: umount <MOUNT_POINT>

​
agentfs serve mcp

Start an MCP (Model Context Protocol) server. 
agentfs serve mcp <ID_OR_PATH> [OPTIONS]
Options:
OptionDescription
--tools <TOOLS>Comma-separated list of tools
Available Tools:
CategoryTools
Filesystemread_file, write_file, readdir, mkdir, remove, rename, stat, access
Key-Valuekv_get, kv_set, kv_delete, kv_list
Examples: 
agentfs serve mcp my-agent
agentfs serve mcp my-agent --tools read_file,readdir,stat

​
agentfs serve nfs

Start an NFS server. 
agentfs serve nfs <ID_OR_PATH> [OPTIONS]
Options:
OptionDescription
--bind <IP>IP to bind (default: 127.0.0.1)
--port <PORT>Port (default: 11111)
Example: 
agentfs serve nfs my-agent --bind 0.0.0.0 --port 2049
Mounting: 
mount -t nfs -o vers=3,tcp,port=11111,mountport=11111,nolock localhost:/ /mnt

​
agentfs sync

Synchronize with a remote Turso database. 
agentfs sync <ID_OR_PATH> <SUBCOMMAND>
Subcommands:
CommandDescription
pullPull remote changes
pushPush local changes
statsView sync statistics
checkpointCreate checkpoint
Example: 
agentfs sync my-agent pull
agentfs sync my-agent push

​
agentfs fs

Filesystem operations on agent databases.

​
agentfs fs ls

agentfs fs ls <ID_OR_PATH> [FS_PATH]
List files. Output: f <name> for files, d <name> for directories.

​
agentfs fs cat

agentfs fs cat <ID_OR_PATH> <FILE_PATH>
Display file contents.

​
agentfs fs write

agentfs fs write <ID_OR_PATH> <FILE_PATH> <CONTENT>
Write content to a file. Examples: 
agentfs fs ls my-agent
agentfs fs cat my-agent /config.json
agentfs fs write my-agent /hello.txt "Hello, world!"

​
agentfs diff

Show filesystem changes in overlay mode. 
agentfs diff <ID_OR_PATH>

​
agentfs timeline

Display agent action timeline. 
agentfs timeline [OPTIONS] <ID_OR_PATH>
Options:
OptionDescription
--limit <N>Limit entries (default: 100)
--filter <TOOL>Filter by tool name
--status <STATUS>Filter: pending, success, error
--format <FORMAT>Output: table, json
Examples: 
agentfs timeline my-agent
agentfs timeline my-agent --filter web_search --status error
agentfs timeline my-agent --format json

​
agentfs completions

Manage shell completions. 
agentfs completions install [SHELL]
agentfs completions uninstall [SHELL]
agentfs completions show
Supported: bash, zsh, fish, powershell

​
Environment Variables

Variables set inside the sandbox:
VariableDescription
AGENTFSSet to 1 inside sandbox
AGENTFS_SANDBOXSandbox type
AGENTFS_SESSIONSession ID

​
Files

PathDescription
.agentfs/<ID>.dbAgent filesystem database
~/.config/agentfs/Configuration directory

​
See Also

Installation

Installation instructions

Sandbox Guide

Running agents in sandboxes