Quick Start

1. Install

git clone https://github.com/mmTheBest/arxie.git
cd arxie

python -m venv .venv
source .venv/bin/activate
pip install -e .

If you specifically want local embedding-model dependencies on the host, install:

pip install -e .[local-embeddings]

2. Configure

cp .env.example .env

Set at least:

• OPENAI_API_KEY

For the full self-hosted stack, .env.example also includes the Paperbase runtime variables for PostgreSQL, Elasticsearch, Redis, MinIO-compatible object storage, queue dispatch, cache lifecycle, and semantic search configuration.

Important runtime defaults:

• PAPERBASE_WORKER_QUEUE_BACKEND=redis in the shipped server stack
• PAPERBASE_OBJECT_STORE_BACKEND=s3 in the shipped server stack
• PAPERBASE_EMBEDDING_PROVIDER=openai for production semantic retrieval

If you intentionally want a lighter local process mode, you can switch to:

• PAPERBASE_WORKER_QUEUE_BACKEND=db
• PAPERBASE_OBJECT_STORE_BACKEND=filesystem
• PAPERBASE_EMBEDDING_PROVIDER=deterministic

3. Start The Self-Hosted Stack

Start infrastructure:

docker compose -f infra/docker-compose.paperbase.yml up -d postgres elasticsearch minio redis

Apply schema migrations:

docker compose -f infra/docker-compose.paperbase.yml run --rm paperbase-migrate

Start the API and worker:

docker compose -f infra/docker-compose.paperbase.yml up -d paperbase-api paperbase-worker

Shortcut Launch

If you want a more app-like local workflow, use the launcher command:

arxie-local run

That boots the lighter single-user local stack, waits for readiness, and opens /app. By default it starts PostgreSQL, MinIO, Redis, the API, and the worker. If you explicitly want the heavier backend-search service too, use:

arxie-local run --with-search

Other useful shortcuts:

arxie-local open
arxie-local down
arxie-local run --rebuild
arxie-local install-shortcut

arxie-local install-shortcut writes a double-clickable Arxie.command launcher to your Desktop by default.

On the first launch, Arxie may need a few minutes to start Colima, build the application images, and boot the local stack. The shipped local Compose profile is tuned for a single-user machine, including a smaller Elasticsearch heap so the default stack can run on modest laptop memory.

For the single-user local path, Arxie does not hard-block readiness on the search backend. The default launcher path skips Elasticsearch entirely so parse, extraction, and the dashboard remain reliable on a modest laptop. The local Compose services mount the current src/ and services/ directories, so code updates are picked up on restart. Use arxie-local run --rebuild only after dependency or Dockerfile changes. If you later start Arxie with --with-search, the workspace can use the backend search surface when Elasticsearch is healthy.

Local Process Mode

If you prefer running the services without Compose:

paperbase-db upgrade
paperbase-api
paperbase-worker

In this mode, the default .env.example still points at the self-hosted stack. If you want a no-MinIO/no-Redis local run, switch the queue, object-store, and embedding settings as described above before launching the processes.

Useful make targets:

make paperbase-db-upgrade
make paperbase-api
make paperbase-worker
make paperbase-compose-config

Product Architecture

src/ra/                 Assistant workflows, CLI, and legacy REST API
src/paperbase/          Canonical schema, ingest, parse, extract, search
services/paperbase_api/ Browser-facing corpus API and UI
services/paperbase_worker/ Background job execution
infra/                  Self-hosting stack and environment files

Detailed architecture, planning notes, tests, and internal developer process files live on the private development branch, not on this release branch.

License

MIT