anchorai-sdk

Official Python SDK for Anchor AI (Fathom-1) — the self-hosted AI assistant built into Anchor Cloud. Chat with it from Python, or launch a polished local web chat UI with a single command. Fathom-1 can read your vault's metadata and act on it directly — organizing files into folders, finding duplicates, deleting on confirmation, bundling a folder into a zip — using your real account.

• Install
• Quickstart
• The chat UI
• Signing in: password vs. API key
• What Fathom-1 can actually do
• API reference
• Error handling
• Requirements
• Security notes

Install

pip install anchorai-sdk

The import name is anchorai (the PyPI distribution name and the Python package name don't have to match — same as beautifulsoup4 → import bs4):

from anchorai import AnchorAI

Quickstart

from anchorai import AnchorAI

# Sign in the same way you would in the app or dashboard
client = AnchorAI.login(email="you@example.com", phone="+15550100", password="...")

reply = client.ask("Organize my vault into folders by file type")
print(reply)

for m in client.history():
    print(m["role"], ":", m["message"])

The chat UI

Beyond the library, this package installs an anchorai command that opens a real chat window in your browser — no code required:

anchorai

This opens http://127.0.0.1:8420 with a sign-in screen (same email, phone, and password as the app). Everything after that is a normal chat interface talking to your account's Fathom-1, with the same tool-driven actions (organize, delete-with-confirmation, folder downloads) as the app itself.

Useful flags:

anchorai --port 9000              # run on a different local port
anchorai --no-browser             # don't auto-open a browser tab
anchorai --api-key ac_live_...    # skip the sign-in screen, use a key instead

The whole thing runs entirely on your machine — the only outbound network calls are to anchorcloud.org, and your session token never leaves the local Python process it's held in (no browser storage, no disk).

Signing in: password vs. API key

Two ways to authenticate, and both produce the exact same kind of client:

Password — same credentials as the app/dashboard, good for interactive use (the chat UI defaults to this):

client = AnchorAI.login(email="you@example.com", phone="+15550100", password="...")

API key — generated once from dashboard.anchorcloud.org → API Keys → Generate New Key, good for scripts/automation where you don't want a password sitting in code. It's the same key the anchorcloud library uses — one key authenticates both file storage and chat, since they share the same account and server-side auth:

client = AnchorAI(api_key="ac_live_...")

The key's secret is shown once at creation — store it in an environment variable or secrets manager. It can't be shown again later, only revoked and replaced.

import os
client = AnchorAI(api_key=os.environ["ANCHORCLOUD_API_KEY"])

What Fathom-1 can actually do

Because Fathom-1 has tool-calling access to your real vault (not just conversation), asking it things like these actually changes your account, the same way clicking the equivalent button in the app would:

• "Organize my vault into folders" — sorts unfiled files by type.
• "Move invoice.pdf into Finance" — moves a specific file.
• "Delete the old screenshots" → "yes, go ahead" — searches first, only deletes after you explicitly confirm in the conversation.
• "What's wasting space in my vault?" → "clean it up" — finds duplicate and stale (90+ day untouched) files, deletes them after confirmation.
• "Download my Photos folder" — bundles every file in a folder into a zip. Decryption and zipping happen in whichever client is running (the chat UI, or your own script via anchorcloud's download_folder()) — the server never has the keys to do this itself.
• Adding/renaming/removing contacts, sharing a file or folder with one.

It never sees decrypted file contents — only metadata (name, size, mime type, extension, upload date, hash) — since Anchor Cloud is zero-knowledge end-to-end for file storage.

API reference

AnchorAI(api_key, base_url="https://anchorcloud.org")

Creates a client using an API key. No network call until the first method.

AnchorAI.login(email, phone, password, base_url="https://anchorcloud.org") -> AnchorAI

Static method. Signs in like the app does and returns a ready-to-use client.

client.ask(message) -> str

Sends a message, returns just the reply text.

client.send(message) -> dict

Sends a message, returns the full response dict — {"reply": str} at minimum, plus type/files/folder/pendingDelete/reorganized when a tool call produced one of those signals.

client.history() -> list[dict]

Returns this account's saved conversation: [{"role": ..., "message": ..., "created_at": ...}, ...].

Error handling

All errors are subclasses of anchorai.AnchorAIError:

from anchorai import AnchorAI, AuthError, ApiError

try:
    client = AnchorAI.login(email="you@example.com", phone="+15550100", password="...")
    client.ask("hello")
except AuthError:
    print("Login failed, or the API key is missing/revoked.")
except ApiError as e:
    print(f"Server error ({e.status_code}): {e}")

• AuthError — login failed, or an API key is empty/rejected/revoked.
• ApiError — any other non-success response; e.status_code holds the HTTP status.

Requirements

• Python 3.9+
• requests (installed automatically as a dependency)

Security notes

• A session token from login() and an API key are both bearer credentials — anyone holding one can chat as you and trigger any of Fathom-1's tools (including deletes, after confirmation) for as long as it's valid.
• The chat UI keeps your session token in the local Python process's memory only — never in browser localStorage/cookies, never written to disk.
• Fathom-1 only ever receives file metadata, never decrypted contents — consistent with Anchor Cloud's zero-knowledge architecture.

License

MIT — see LICENSE.