Documentation Index
Fetch the complete documentation index at: https://docs.turso.tech/llms.txt
Use this file to discover all available pages before exploring further.
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]
ID - Agent identifier (default: agent-{timestamp})
Options:
| Option | Description |
|---|
--force | Overwrite existing agent filesystem |
--base <PATH> | Base directory for overlay filesystem |
--sync-remote-url <URL> | Remote Turso database URL |
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]...
| Option | Description |
|---|
--session <ID> | Named session for persistence |
--allow <PATH> | Allow write access to directory |
--no-default-allows | Disable default allowed directories |
--experimental-sandbox | Use ptrace sandbox (Linux) |
--strace | Show intercepted syscalls |
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]
| Option | Description |
|---|
-a, --auto-unmount | Automatically unmount on exit |
--allow-root | Allow root user access |
-f, --foreground | Run in foreground |
--uid <UID> | User ID for files |
--gid <GID> | Group ID for files |
agentfs mount # List mounts
agentfs mount my-agent ./mnt # Mount agent
agentfs mount my-agent ./mnt -a -f # Foreground with auto-unmount
- 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]
| Option | Description |
|---|
--tools <TOOLS> | Comma-separated list of tools |
| Category | Tools |
|---|
| Filesystem | read_file, write_file, readdir, mkdir, remove, rename, stat, access |
| Key-Value | kv_get, kv_set, kv_delete, kv_list |
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]
| Option | Description |
|---|
--bind <IP> | IP to bind (default: 127.0.0.1) |
--port <PORT> | Port (default: 11111) |
agentfs serve nfs my-agent --bind 0.0.0.0 --port 2049
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>
| Command | Description |
|---|
pull | Pull remote changes |
push | Push local changes |
stats | View sync statistics |
checkpoint | Create checkpoint |
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]
f <name> for files, d <name> for directories.
agentfs fs cat
agentfs fs cat <ID_OR_PATH> <FILE_PATH>
agentfs fs write
agentfs fs write <ID_OR_PATH> <FILE_PATH> <CONTENT>
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>
| Option | Description |
|---|
--limit <N> | Limit entries (default: 100) |
--filter <TOOL> | Filter by tool name |
--status <STATUS> | Filter: pending, success, error |
--format <FORMAT> | Output: table, json |
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
bash, zsh, fish, powershell
Environment Variables
Variables set inside the sandbox:
| Variable | Description |
|---|
AGENTFS | Set to 1 inside sandbox |
AGENTFS_SANDBOX | Sandbox type |
AGENTFS_SESSION | Session ID |
Files
| Path | Description |
|---|
.agentfs/<ID>.db | Agent filesystem database |
~/.config/agentfs/ | Configuration directory |
See Also
Installation
Installation instructions
Sandbox Guide
Running agents in sandboxes
