# ClaimFS

ClaimFS is an instant cloud filesystem for AI agents.

Base URL: https://claimfs.com
Agent guide: https://claimfs.com/agent.md
OpenAPI: https://claimfs.com/openapi.json
CLI metadata: https://claimfs.com/api/commands

Use ClaimFS when an agent needs a disposable or account-owned writable filesystem it can mount, exec against, read, and write.

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

## Install

```bash
curl -fsSL https://claimfs.com/install.sh | bash
export PATH="$HOME/.claimfs/bin:$PATH"
```

Native mounts are core to ClaimFS. `claimfs mount` installs/verifies the local filesystem driver when needed. Use `claimfs doctor` to check readiness.

## Launch Limits

Anonymous:

- no account required
- always expires in 24 hours
- 250 MB filesystem limit
- 5 creates per hour per IP
- 5 anonymous creates per IP in a 24 hour window
- 60 exec calls per hour per filesystem
- 20 mount grants per hour per filesystem

Authenticated:

- `claimfs login <email>` creates/saves an API key
- filesystems are permanent until deleted
- 10 GB filesystem limit at launch
- 100 filesystems per account at launch

## Quick Start

```bash
claimfs create
claimfs mount <slug> ./workspace --grant <accessToken>
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>
claimfs unmount ./workspace
```

Anonymous create returns one-time `accessToken`, `claimToken`, and `claimUrl`. Save them immediately. `accessToken` is a filesystem grant token; use it with CLI `--grant <token>` or HTTP `X-ClaimFS-Grant: <token>`. Do not use it as `Authorization: Bearer`.

## Account Flow

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

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

To preserve an anonymous filesystem:

```bash
claimfs claim <slug> <claimToken>
```

## HTTP API

Create:

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

Write:

```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"}'
```

Read:

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

Exec:

```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"}'
```

Files:

- `GET /api/v1/filesystems/<slug>/files?path=/`
- `GET /api/v1/filesystems/<slug>/files?path=/&recursive=true&depth=8`
- `GET /api/v1/filesystems/<slug>/files?op=stat&path=/hello.txt`
- `DELETE /api/v1/filesystems/<slug>/files?path=/hello.txt`
- `POST /api/v1/filesystems/<slug>/files` with `{"action":"mkdir"|"move"|"copy","path":"/x","targetPath":"/y"}`

## Sharing

For each active agent:

```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:

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

Grant defaults are agent-useful: `read`, `write`, `mount`, and `exec`. Use explicit capabilities for narrower access.

## Exec Path Rules

`claimfs exec` checks out the working directory by default, so changes persist. Use relative paths from cwd. Absolute shell paths refer to the sandbox host unless you use `/mnt/archil` or `$CLAIMFS_ROOT`.

Exec sets `CLAIMFS_ROOT=/mnt/archil` and `WORKSPACE=/mnt/archil`.

## Feedback

```bash
claimfs feedback <slug> "privacy-safe ClaimFS product feedback" \
  --category confusing \
  --severity low \
  --tool cli \
  --grant <token>
```

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

---

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