AMETHYST

A personal operating system: one AI agent over your files, shell, tasks, calendar, notes and connected services. Single-user and local-first — your data stays in a SQLite file on your machine, your secrets stay in the OS keychain, and nothing is sent anywhere except to the model provider you choose.

⚡ Quick Start

📖 Full guide: See QUICKSTART.md for the 2-minute setup, connecting Ollama (free local models), and API keys.

1-Line Automated Launcher (macOS / Linux / WSL2)

git clone <this repository> && cd amethyst
./run.sh
# → Opens http://127.0.0.1:8000 automatically

(On Windows Command Prompt, run run.bat. On Mac/Linux, run ./run.sh)

The script checks prerequisites, creates .venv, installs dependencies from requirements.txt, builds the web UI, initializes the local SQLite database, and opens AMETHYST in your default browser.

• Run ./run.sh --setup (or run.bat --setup) for the interactive configuration wizard (API keys, OAuth, Cloudflare, connectors).
• Run ./run.sh --dev for concurrent backend + frontend hot-reloading.
• Run ./run.sh --doctor to run diagnostics.
• See CONFIGURATION_GUIDE.md for complete setup instructions for Google Workspace, Microsoft To Do, Cloudflare Workers, and Library capture.

🐳 Run it in Docker

git clone <this repository> && cd amethyst
docker compose up
# → http://127.0.0.1:8000

One image, one process, one port: the API and the built interface come from the same origin, so there is no second service and no cross-origin request to configure. First run walks you through pointing it at a model and signing into whatever connectors you want; state lives in two volumes (./data/amethyst for the library and database, a named volume for connector tokens) and survives restarts.

Exposure warning, unhedged

AMETHYST has no authentication. Anything that can reach port 8000 can read your files, run shell commands and read your mail. The compose file publishes on 127.0.0.1 only — do not change that without putting an authenticating reverse proxy in front of it (deployment.md).

Google and Spotify sign-ins need network_mode: host (the Linux default here); the docker notes say why, and what a container degrades at honestly — desktop notifications, the shell sandbox on hardened hosts, office conversion.

Developers: CONTRIBUTING.md covers the dev install, the one-worker rule, the secrets rule and the -e rule — three traps a container image and a public repository each have one of.

What it does

Ask for something in one line. AMETHYST decides which of its tools to use, asks permission before anything that writes or runs, and shows you exactly what it did.

That turn is three tool calls — a web search, then two fetches — resolved without being nudged. The agent loop treats an empty or truncated reply as unfinished work and continues rather than ending the turn on a blank bubble.

Everything that writes or runs asks first, and the prompt names the operation, not just the tool, so approving a read-only shell command never approves a destructive one.

Manual Installation (pip or uv)

python3 -m venv .venv
source .venv/bin/activate               # Windows: .venv\Scripts\activate
pip install -r requirements.txt         # or: uv pip install -r requirements.txt

amethyst init                               # ~/.amethyst, the database, default config
amethyst doctor                             # what is configured and what is missing

cd frontend && npm install && npm run build
cd ..
amethyst serve --open                       # http://127.0.0.1:8000

Point it at a model. Ollama is preconfigured; a cloud provider keeps its key in the OS keychain, never in the config file:

amethyst providers catalogue               # what AMETHYST knows how to configure
amethyst providers add anthropic
amethyst secrets set amethyst/anthropic        # prompts, so the key stays out of shell history

Any OpenAI-compatible endpoint — vLLM, LM Studio, a proxy — works with no code change:

providers:
  - name: my-vllm
    base_url: http://localhost:8000/v1
    default_model: llama-3.1-8b
    context_window: 32768              # optional; otherwise it is guessed

Configure a second provider and a turn survives the first one being down: it falls back, and says which provider answered. See providers.md.

The interface, room by room

One React app over the same API the CLI uses. Every image below is a real screenshot of a running instance.

View	What lives there
Chat ⌘1	The transcript, the composer, the + menu — files, skills, connectors, the working directory — and inline permission prompts.
Today ⌘8	Calendar, task buckets, unread mail and connected tools on one page, under a briefing written each morning.
Tasks ⌘2	Task lists as a board of cards; My Day shows only what you intend to do today.
Mail ⌘3 (beta)	Gmail read directly — not through the connector — with a search that jumps.
Skills & connectors ⌘4	Two tabs, one page: what is added and what could be. OAuth sign-ins and credentials finish here.
Automations ⌘5 (beta)	A prompt and an interval, run as an ordinary turn while AMETHYST is open.
Memory ⌘6	Standing facts extracted after a turn, recalled in later conversations.
Library ⌘9	What you have read and saved — fetched, summarised, tagged and searchable.
Activity ⌘7	Every tool call, with the decision that allowed it. Reached from Settings.
Status	Providers, tools, skills and what needs attention. Reached from the degraded banner or the palette (⌘K).

Beta pages (Mail, Automations) are off until Settings → Beta pages is enabled.

Every action in the app is also in the command palette (⌘K), the + menu gathers everything the agent can be given for the next message, and ? lists every keyboard binding.

Press ? in the app for every keyboard binding; interface.md covers how each view is built and why it is this one.

What needs what — and what merely degrades

The honest table: most missing pieces cost a feature quietly rather than break a start.

Connectors: zero-config, and bring-your-own

Works with nothing to register — the connector signs into your account, no app of yours needed:

• fetch, memory, playwright, chrome-devtools — no auth at all
• vercel — its authorization server accepts dynamic registration, so AMETHYST registers on first sign-in
• microsoft-todo — Microsoft's own public client, device-code flow
• github, linkedin, tavily, exa, firecrawl — an API key or an app registration of your own, pasted into the row

Needs an OAuth app registration of your own:

• Google — and it cannot honestly be called zero-config anyway: while the app is in Testing, Google expires a test user's grant — the refresh token included — seven days after it is given, and publishing is blocked by restricted Gmail scopes (paid CASA assessment) and Branding fields that need a Search-Console-verified domain. AMETHYST's mechanism for a shared registration exists (AMETHYST_DEFAULT_GOOGLE_*), ships with no value, and would not remove the weekly renewal. The connector announces its grant age before a tool call finds out. connectors.md has the full accounting.
• Spotify — 25 users in Development Mode, each added by email in the dashboard.

A friend contributing on their own machine never reaches yours: the shared registration, where one exists, identifies the software; every token is minted per install and stays there.

What works

Each of these was exercised end to end, not just wired up.

The agent loop. Reason → act → observe, with guards on iterations, wall-clock time, repeated calls and continuations. Streaming, retry on transient provider failures, and a stop that interrupts the