# ClaimFS Agent Guide

ClaimFS gives agents an instant writable filesystem in the cloud.

## 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

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

Token rule:
- accessToken and grant tokens go in --grant <token> for CLI commands.
- HTTP requests use 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>

Run commands:
claimfs exec <slug> --grant <accessToken> -- "pwd && ls -la"
claimfs write <slug> /hello.txt "hello" --grant <accessToken>
claimfs read <slug> /hello.txt --grant <accessToken>
claimfs files <slug> / --recursive --grant <accessToken>

Give another agent a workspace:
claimfs agent join <slug> claude --agent-id claude --grant <accessToken>

Unmount:
claimfs unmount ./workspace
```

## Modes

Anonymous filesystems:

- no account required
- expire after 24 hours
- 250 MB launch limit
- 5 creates per hour per IP
- return `accessToken`, `claimToken`, and `claimUrl` once
- can be mounted, executed against, and shared with grants

Authenticated filesystems:

- created after `claimfs login <email>`
- permanent until deleted
- 10 GB launch limit
- 100 filesystems per account at launch

## Login

```bash
claimfs login user@example.com
```

ClaimFS emails a one-time code. The CLI prompts for the code, verifies it, and stores the API key in `~/.claimfs/credentials`.

To preserve an anonymous filesystem:

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

## HTTP Hello World

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

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).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

Use `claimfs agent join` for each active agent. It creates a normal directory like `/agents/claude` plus a scoped grant.

```bash
claimfs agent join <slug> claude --agent-id claude --grant <accessToken>
claimfs exec <slug> --grant <workspaceToken> --workspace /agents/claude -- "echo hi > hello.txt"
claimfs mount <slug> ./workspace --grant <workspaceToken>
```

Direct grants are also available:

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

Grant defaults are intentionally useful for agents: `read`, `write`, `mount`, and `exec`. Pass explicit `--capability` flags only when you want narrower access.

## Exec Paths

`claimfs exec` checks out its working directory by default so file changes persist. Commands run with the selected filesystem path as cwd, so use relative paths:

```bash
claimfs exec <slug> --grant <token> --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 you explicitly use `/mnt/archil` or `$CLAIMFS_ROOT`. Exec sets `CLAIMFS_ROOT=/mnt/archil` and `WORKSPACE=/mnt/archil`.

## Notes For Agents

- Prefer the CLI or REST API over the browser.
- Use `claimfs mount` for normal agent work when native mounts are available.
- Use `claimfs exec`, `claimfs files`, `claimfs read`, and `claimfs write` when mounting is unavailable.
- Use `--` before exec commands that include flags.
- Local mounts are shared by default. Use `--exclusive` only when one process needs ownership.
- After a local mounted write, API or exec readers may need a short retry window while metadata refreshes.
- Do not store production secrets in anonymous filesystems.
- Fetch `/openapi.json` for the API contract and `/api/commands` for CLI metadata.

## Privacy-Safe Feedback

Feedback is optional. Never submit secrets, personal data, proprietary source snippets, raw chat transcripts, customer data, or other sensitive user information.

If ClaimFS blocks progress or behaves unexpectedly:

```bash
claimfs feedback <slug> "exec 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" \
  --suggested-fix "show CLAIMFS_ROOT in the exec quickstart" \
  --tool cli \
  --grant <token>
```

---

- by [cam](https://x.com/financialvice) & [anupam](https://x.com/anupambatra_), [dubdubdub labs](https://www.dubdubdub.xyz/)