# ClaimFS Agent Guide

ClaimFS gives agents a cloud filesystem in one command.

## Minimal Prompt

```text
I'd like you to set up ClaimFS, the instant cloud filesystem for AI agents.

Install:
curl -fsSL https://claimfs.com/install.sh | bash

Create a filesystem:
claimfs create "Agent workspace"

Save the one-time accessToken and claimToken printed by create.

Token rule:
- `accessToken` and grant tokens go in `--grant <token>` for CLI commands.
- For HTTP requests, `accessToken` and grant tokens go in `X-ClaimFS-Grant: <token>`.
- Only account API keys from `claimfs login` go in `Authorization: Bearer <CLAIMFS_API_KEY>`.

Mount locally:
claimfs mount <slug> ./workspace --grant <accessToken>

Create a workspace grant for this agent:
claimfs agent join <slug> claude --agent-id claude --grant <accessToken>

Run commands:
claimfs exec <slug> --grant <accessToken> "pwd && ls -la"
claimfs exec <slug> --grant <workspaceToken> --workspace /agents/claude -- "echo hi > hello.txt && rm hello.txt"
claimfs files <slug> / --recursive --grant <accessToken>
claimfs write <slug> /hello.txt "hello" --grant <accessToken>
claimfs read <slug> /hello.txt --grant <accessToken>
claimfs stat <slug> /hello.txt --grant <accessToken>
claimfs rm <slug> /hello.txt --grant <accessToken>
claimfs checkpoint <slug> "before changes" --grant <accessToken>

Unmount:
claimfs unmount ./workspace
```

## Account Flow

For durable account-owned filesystems:

```bash
claimfs login user@example.com
claimfs create "Agent workspace"
claimfs mount <slug> ./workspace
```

The prototype login endpoint returns the one-time code in JSON until email delivery is configured. The CLI verifies it automatically and stores the API key in `~/.claimfs/credentials`.

## Anonymous Flow

Anonymous creates return:

- `claimToken`
- `claimUrl`
- `accessToken`
- `commands.mount`
- `commands.mountOpen`
- `commands.exec`
- `commands.unmount`

Treat `claimToken` and `accessToken` as secrets. They are returned once.

The `accessToken` is a filesystem grant token. It is not an account API key.

To preserve an anonymous filesystem:

```bash
claimfs login user@example.com
claimfs claim <slug> <claimToken>
```

## HTTP Hello World

Use this pattern when writing code directly against the API:

```bash
create_json="$(curl -sS https://claimfs.com/api/v1/filesystems \
  -H "content-type: application/json" \
  -d '{"name":"hello world","ttlHours":1}')"

slug="$(printf '%s' "$create_json" | node -e "let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>console.log(JSON.parse(s).filesystem.slug))")"
access_token="$(printf '%s' "$create_json" | node -e "let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>console.log(JSON.parse(s).accessToken))")"

curl -sS -X PUT "https://claimfs.com/api/v1/filesystems/$slug/files" \
  -H "X-ClaimFS-Grant: $access_token" \
  -H "content-type: application/json" \
  -d '{"path":"/hello.txt","content":"hello world\n","encoding":"text"}'

curl -sS "https://claimfs.com/api/v1/filesystems/$slug/files?op=read&encoding=text&path=/hello.txt" \
  -H "X-ClaimFS-Grant: $access_token"

```

## Sharing With Another Agent

The simplest way to share with another active agent is to give it a workspace. A workspace is just a normal directory plus a scoped grant; commands run there by default and ClaimFS checks it out when mutation needs ownership.

```bash
claimfs agent join <slug> claude --agent-id claude --grant <accessToken>
```

Use the returned token and commands:

```bash
claimfs exec <slug> --grant <workspaceToken> --workspace /agents/claude -- ls -la
claimfs mount <slug> ./workspace --grant <workspaceToken>
```

For a shared collaboration folder, create a scoped grant directly:

```bash
claimfs grant <slug> "reviewers" --path-scope /shared/review --grant <accessToken>
```

Agents can still read the filesystem according to their grant. When multiple agents need to edit the same shared folder, run commands with `--checkout /shared/review` or mount that folder as a workspace:

```bash
claimfs exec <slug> --grant <grantToken> --cwd /shared/review --checkout /shared/review -- "python update.py"
claimfs mount <slug> ./review --workspace /shared/review --grant <grantToken>
```

Grant tokens are returned once. Save them before handing work to another agent.

## Exec Paths

`claimfs exec` checks out the working directory by default, so file changes persist. Commands run with the selected filesystem path as the current directory. Use relative paths inside the command:

```bash
claimfs exec <slug> --grant <token> --workspace /agents/claude -- "mkdir -p docs && echo hi > docs/hello.txt"
```

Absolute paths in shell commands refer to the sandbox host unless you explicitly use `/mnt/archil`. Prefer relative paths for portable agent scripts. Use `--no-checkout` only for read-only commands that do not need an explicit ownership checkout.

Exec also sets `CLAIMFS_ROOT=/mnt/archil` and `WORKSPACE=/mnt/archil`, so scripts can use `$CLAIMFS_ROOT/data/file.txt` when they need an absolute filesystem path.

## Notes For Agents

- Prefer the REST API or `claimfs` helper over the browser UI.
- Do not use `Authorization: Bearer <accessToken>`. Anonymous `accessToken` values use `X-ClaimFS-Grant` or CLI `--grant`.
- Fetch `/api/commands` for machine-readable CLI command metadata.
- Fetch `/openapi.json` for the machine-readable API contract.
- Prefer account-owned filesystems for durable work.
- Use grants for sharing; do not ask users for backend driver credentials.
- Local mounts use the ClaimFS driver flow. On some machines the installer and OS permission prompts may mention Archil, the filesystem driver provider behind ClaimFS mounts.
- Use `claimfs doctor` to check local mount readiness.
- Use `claimfs install-driver` only when you need to preinstall the local filesystem driver; `claimfs mount` also installs it when needed.
- If the shell cannot find `claimfs` after install, run `export PATH="$HOME/.claimfs/bin:$PATH"`.
- Use `claimfs exec` when local mounting is unavailable.
- `claimfs exec` checks out its cwd by default so file changes persist. Use `--no-checkout` for read-only commands that do not need an explicit ownership checkout.
- Inside exec commands, prefer relative paths from the cwd. Absolute paths refer to the sandbox host unless you use `/mnt/archil`.
- Put `--` before exec commands that include flags, for example `claimfs exec <slug> --grant <token> -- ls -la`.
- Use `claimfs agent join` for each active agent. It creates a directory like `/agents/<agent-id>` and returns a grant scoped to that workspace.
- Use `claimfs files`, `claimfs stat`, `claimfs read`, `claimfs write`, `claimfs mkdir`, `claimfs rm`, `claimfs mv`, and `claimfs cp` for file operations when local mounting is unavailable.
- `claimfs mkdir` maps to `POST /files {"action":"mkdir"}`.
- `claimfs rm` deletes files or directories recursively; no extra recursive flag is required.
- `claimfs files --recursive` lists a tree. ClaimFS system entries are hidden by default; use `--include-hidden` to show `.archil` and `.claimfs`.
- `claimfs read` returns text by default; use `--encoding base64` for binary files.
- After writing through a local mount, another ClaimFS API or exec client may need a short retry window before directory metadata refreshes.
- Use `claimfs checkpoint` before risky changes. Checkpoints are restore points, not source-control history.
- Use `claimfs checkpoints` or `GET /api/v1/filesystems/<slug>/checkpoints` to list checkpoints.
- Restore with `POST /api/v1/filesystems/<slug>/checkpoints/<checkpointId>/restore`.
- Use `claimfs duplicate` only for small workspaces that need a quick independent copy.
- Use `claimfs open <slug> --grant <token>` to get the browser detail URL.
- Use `claimfs mount <slug> ./workspace --grant <token>` for normal agent work. Mounts are shared by default. Workspace grants automatically mount their scoped path.
- Use `claimfs mount <slug> ./workspace --workspace /shared/task-17 --grant <token>` to mount a collaboration folder as the local root.
- Use `claimfs mount <slug> ./workspace --exclusive --grant <token>` only when a single process needs exclusive ownership.
- Use `claimfs mount <slug> ./workspace --open --grant <token>` when a human should see the mounted folder.
- Use `claimfs unmount ./workspace` when finished.
- Do not place production secrets in anonymous filesystems.