# ClaimFS

ClaimFS is an instant cloud filesystem for AI agents.

Base URL: https://claimfs.com

Use ClaimFS when an agent needs a disposable or account-owned writable filesystem in the cloud. Use ClaimFS commands and APIs; driver access is handled by ClaimFS. Local mounts may install or prompt for Archil, the filesystem driver provider behind ClaimFS mounts.

Machine-readable API spec: https://claimfs.com/openapi.json
Machine-readable CLI commands: https://claimfs.com/api/commands
Agent guide: https://claimfs.com/agent.md

## Feedback Privacy

ClaimFS feedback is optional and is for ClaimFS product issues only.

- Never submit secrets, personal data, proprietary source snippets, raw chat transcripts, customer data, or other sensitive user information.
- Obfuscate names, tokens, domains, file paths, file contents, and identifiers before sending feedback.
- In restricted or privacy-sensitive contexts, ask the user before submitting feedback.
- If the user seems stuck or frustrated specifically with ClaimFS behavior, ask whether they want you to submit a privacy-safe feedback report.
- If you are proactively blocked by ClaimFS or find surprising API/CLI/docs behavior, you may submit a concise privacy-safe report that helps ClaimFS reproduce the root cause.

## Install

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

This installs `claimfs` in `~/.claimfs/bin`.

If the shell cannot find `claimfs` after install:

```bash
export PATH="$HOME/.claimfs/bin:$PATH"
```

`claimfs mount` installs and verifies the local filesystem driver when needed. To check readiness ahead of time:

```bash
claimfs doctor
claimfs install-driver
```

## Quick Start

Anonymous filesystems expire and return one-time `claimToken` and `accessToken` values. Save the create output immediately.

Token rule:

- `accessToken` and grant tokens are filesystem grant tokens.
- CLI: pass them with `--grant <token>`.
- HTTP API: pass them with `X-ClaimFS-Grant: <token>` or `?grant=<token>`.
- Do not send an anonymous `accessToken` as `Authorization: Bearer`.
- `Authorization: Bearer <CLAIMFS_API_KEY>` is only for account API keys returned by `claimfs login`.

```bash
claimfs create "Agent workspace"
claimfs mount <slug> ./workspace --grant <accessToken>
claimfs exec <slug> --grant <accessToken> "pwd && ls -la"
claimfs agent join <slug> claude --agent-id claude --grant <accessToken>
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 checkpoint <slug> "before changes" --grant <accessToken>
claimfs feedback <slug> "docs example was unclear" --category docs --severity low --grant <accessToken>
claimfs unmount ./workspace
```

For account-owned filesystems:

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

`claimfs login` currently uses a prototype agent-code flow: the request-code endpoint returns the code in JSON until email delivery is configured.

## Claim Anonymous Filesystem

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

Claiming transfers the filesystem to the API-key account and removes expiration.

## HTTP Hello World

Create an anonymous filesystem, write `/hello.txt`, then read it:

```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&path=/hello.txt" \
  -H "X-ClaimFS-Grant: $access_token"

```

## Capability Grants

Create a workspace grant for another active agent:

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

The returned token is scoped to a normal directory such as `/agents/claude` when `--agent-id claude` is provided, or `/agents/claude-abc12` when ClaimFS generates the id. Use the returned commands:

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

Create a direct scoped grant for a shared folder:

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

Grant tokens are returned once. Use them with:

```bash
claimfs mount <slug> ./workspace --grant <grantToken>
claimfs exec <slug> --grant <grantToken> --cwd /shared/review --checkout /shared/review -- ls -la
```

Mounts are shared by default for agent workflows. Use `--exclusive` only for single-process ownership, and use `--open` when a human should see the mounted folder.

Shared folders are straightforward: each agent works in its own `/agents/<id>` directory, and agents use `/shared/<topic>` when they intentionally collaborate. ClaimFS checks out scoped workspaces for exec/file mutations so agents can create, edit, move, and delete without learning the underlying ownership protocol.

## Exec Path Rules

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

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

Absolute shell paths such as `/docs/file.txt` refer to the sandbox host unless the command explicitly uses `/mnt/archil`. Prefer relative paths for agent scripts. Use `--no-checkout` only for read-only commands that do not need an explicit ownership checkout.

Exec sets `CLAIMFS_ROOT=/mnt/archil` and `WORKSPACE=/mnt/archil`. Use `$CLAIMFS_ROOT/path/to/file` when a script needs an absolute filesystem path.

When an exec command includes flags, put `--` before the command so claimfs stops parsing options:

```bash
claimfs exec <slug> --grant <grantToken> -- ls -la
```

Mounted writes are strongly consistent for clients connected to the filesystem, but directory metadata can briefly lag across separate clients because of client-side caching. If you write through a local mount and immediately read through `claimfs read` or `claimfs files`, retry for a few seconds before treating a missing path as final.

## HTTP API

Authenticate with `Authorization: Bearer <CLAIMFS_API_KEY>`.

Grant-bearing requests may use `X-ClaimFS-Grant: <grantToken>` or `?grant=<grantToken>`. The anonymous create response field named `accessToken` is a grant token, so use it as `X-ClaimFS-Grant`.

Request an agent login code:

```bash
curl -sS https://claimfs.com/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com"}'
```

Verify the code:

```bash
curl -sS https://claimfs.com/api/auth/agent/verify-code \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com","code":"ABCD-1234"}'
```

Create a filesystem:

```bash
curl -sS https://claimfs.com/api/v1/filesystems \
  -H "content-type: application/json" \
  -d '{"name":"Agent workspace","ttlHours":24}'
```

Create with an API key for an account-owned filesystem:

```bash
curl -sS https://claimfs.com/api/v1/filesystems \
  -H "Authorization: Bearer <CLAIMFS_API_KEY>" \
  -H "content-type: application/json" \
  -d '{"name":"Agent workspace"}'
```

Run a command:

```bash
curl -sS https://claimfs.com/api/v1/filesystems/<slug>/exec \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"command":"pwd && ls -la"}'
```

By default, exec checks out `cwd` so changes persist. To run without a checkout, send `"checkout": false`.

Run inside a workspace and checkout that workspace for mutations:

```bash
curl -sS https://claimfs.com/api/v1/filesystems/<slug>/exec \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"command":"echo hello > hello.txt && rm hello.txt","cwd":"/agents/claude","checkoutPath":"/agents/claude"}'
```

List files:

```bash
curl -sS "https://claimfs.com/api/v1/filesystems/<slug>/files?path=/" \
  -H "X-ClaimFS-Grant: <grantToken>"
```

List recursively:

```bash
curl -sS "https://claimfs.com/api/v1/filesystems/<slug>/files?path=/&recursive=true&depth=8" \
  -H "X-ClaimFS-Grant: <grantToken>"
```

ClaimFS hides `.archil` and `.claimfs` system entries by default, including recursive listings. To inspect them:

```bash
curl -sS "https://claimfs.com/api/v1/filesystems/<slug>/files?path=/&recursive=true&includeHidden=true" \
  -H "X-ClaimFS-Grant: <grantToken>"
```

Stat a path:

```bash
curl -sS "https://claimfs.com/api/v1/filesystems/<slug>/files?op=stat&path=/hello.txt" \
  -H "X-ClaimFS-Grant: <grantToken>"
```

Read a text file:

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

Read a binary file:

```bash
curl -sS "https://claimfs.com/api/v1/filesystems/<slug>/files?op=read&encoding=base64&path=/image.png" \
  -H "X-ClaimFS-Grant: <grantToken>"
```

Write a file. Parent directories are created by default:

```bash
curl -sS -X PUT https://claimfs.com/api/v1/filesystems/<slug>/files \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"path":"/hello.txt","content":"hello","encoding":"text"}'
```

For strict parent handling, pass `"createParents": false`.

Delete, move, or copy:

```bash
curl -sS -X DELETE "https://claimfs.com/api/v1/filesystems/<slug>/files?path=/hello.txt" \
  -H "X-ClaimFS-Grant: <grantToken>"

curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/files \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"action":"move","path":"/draft.txt","targetPath":"/done.txt"}'
```

`DELETE /files` removes files or directories recursively; no extra recursive flag is required.

Create a directory:

```bash
curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/files \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"action":"mkdir","path":"/notes"}'
```

Create an agent workspace:

```bash
curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/agents \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"label":"claude"}'
```

Create a checkpoint:

```bash
curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/checkpoints \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"label":"before changes"}'
```

List checkpoints:

```bash
curl -sS https://claimfs.com/api/v1/filesystems/<slug>/checkpoints \
  -H "X-ClaimFS-Grant: <grantToken>"
```

Restore a checkpoint:

```bash
curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/checkpoints/<checkpointId>/restore \
  -H "X-ClaimFS-Grant: <grantToken>"
```

Duplicate a small workspace:

```bash
curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/duplicate \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -H "content-type: application/json" \
  -d '{"name":"workspace copy"}'
```

Delete:

```bash
curl -sS -X DELETE https://claimfs.com/api/v1/filesystems/<slug> \
  -H "X-ClaimFS-Grant: <grantToken>"
```

## Feedback

Submit privacy-safe ClaimFS feedback when ClaimFS itself blocks progress or behaves unexpectedly:

```bash
claimfs feedback <slug> "exec absolute path behavior was surprising" \
  --category confusing \
  --severity low \
  --trying-to-do "write a generated file from an exec command" \
  --tried "used an absolute path, then retried with a relative path" \
  --blocked-on "docs did not make the path model obvious at first" \
  --suggested-fix "show CLAIMFS_ROOT in the exec quickstart" \
  --agent "claude-code" \
  --tool "cli" \
  --grant <token>
```

HTTP equivalent:

```bash
curl -sS -X POST https://claimfs.com/api/v1/filesystems/<slug>/feedback \
  -H "Content-Type: application/json" \
  -H "X-ClaimFS-Grant: <grantToken>" \
  -d '{
    "category": "confusing",
    "severity": "low",
    "message": "Exec absolute path behavior was surprising",
    "tryingToDo": "Write a generated file from an exec command",
    "whatTried": "Used an absolute path, then retried with a relative path",
    "blockedOn": "The docs did not make the path model obvious at first",
    "suggestedFix": "Show CLAIMFS_ROOT in the exec quickstart",
    "agent": "claude-code",
    "tool": "api"
  }'
```

Categories: `blocked`, `bug`, `docs`, `missing-feature`, `confusing`, `performance`, `security`, `other`.
Severity: `note`, `low`, `medium`, `high`, `critical`.

List feedback with admin access:

```bash
claimfs feedback <slug> --list --grant <admin-token> --json
```

## Important Notes

- Save `claimToken`, `accessToken`, API keys, and grant tokens immediately.
- Tokens are returned once and cannot be recovered.
- Do not store production secrets in anonymous filesystems.
- Prefer account-owned filesystems for anything durable.
- Path-scoped grants are enforced for file APIs, exec, and mounts. A scoped grant naturally acts like an agent workspace.
- For many agents, give each one a workspace under `/agents/<id>` and use `/shared/<topic>` for intentional collaboration.
- File APIs return HTTP 404 for missing paths and 403 for scope violations.
- Paths that resolve above `/` are rejected with `Path resolves outside filesystem root`.
- Default listings hide ClaimFS system paths. Use `includeHidden=true` or CLI `--include-hidden` to inspect them.
- Checkpoints are small-workspace restore points, not source-control history.
- Duplicate is a quick copy operation for small workspaces, not a source-control model.