Local Standalone Catalog

The exo standalone command lets you run a fully local ArtifactDB catalog stack — no cloud account, no ExoHub deployment required. It is ideal for local development, testing pipelines, or creating a private catalog before migrating to a shared ExoHub deployment.

The stack consists of three processes managed automatically by exo standalone up:

The responses are byte-compatible with the enterprise ArtifactDB API, so datasets cataloged locally round-trip cleanly to a shared ExoHub deployment.

Prerequisites

No manual binary installation is required. On first run, exo standalone up detects missing binaries and prompts:

Install the standalone stack (surreal, versitygw, adb-standalone)? [Y/n]

Confirming downloads all three into <data-dir>/bin/ and caches them for later runs. Subsequent invocations skip the download entirely.

Note: Binaries are stored under <data-dir>/bin/ (default: $XDG_CONFIG_HOME/exo/standalone/bin/).

Starting the Stack

exo standalone up --secret-key mysecret

This starts all three processes in the foreground and writes a default config.yaml the first time. Press Ctrl+C to stop everything gracefully.

Note: --secret-key (or the VERSITYGW_SECRET_KEY environment variable) is required when using the managed versitygw object store.

Flags

Once running, the stack prints the three endpoints:

Stack is up:
  surrealdb      ws://localhost:8000
  versitygw      http://localhost:9100
  adb-standalone http://localhost:8080

Installation Options

For scripted or CI environments, use --yes / -y to skip the confirmation prompt:

exo standalone up --yes --secret-key mysecret

To prevent any binary downloads (e.g. on pre-provisioned hosts where binaries are already in PATH or placed manually):

exo standalone up --no-install --secret-key mysecret

To use specific existing binaries instead of the auto-downloaded ones:

exo standalone up --surreal-bin /usr/local/bin/surreal --adb-bin /opt/bin/adb-standalone --secret-key mysecret

Custom Configuration

On the first run, exo standalone up writes a default config.yaml under <data-dir>/. Edit this file to change ports, bucket names, storage locations, or enable optional features such as semantic search.

Pass --config <path> to use a custom config file:

exo standalone up --config ~/my-adb-config.yaml --secret-key mysecret

Checking Stack Health

exo standalone status

Displays the PID, endpoint, and HTTP health status for each process:

PROCESS        PID    ENDPOINT                  STATUS
surrealdb      12345  ws://localhost:8000        running
versitygw      12346  http://localhost:9100      ok
adb-standalone 12347  http://localhost:8080      ok

Supports --surreal-port, --versitygw-port, --adb-port, and --data-dir to match a non-default stack.

Stopping the Stack

In a second terminal, stop the running stack:

exo standalone down

This sends SIGTERM to each process and removes the PID file. Pressing Ctrl+C in the foreground terminal where up is running also stops everything gracefully.

Loading Data

Bulk-loading an Existing Snapshot (seed)

Populate the catalog from an NDJSON snapshot — for example, from an adb-capture dump or a migration from a private deployment:

exo standalone seed documents.ndjson

Each line must be a complete ArtifactDB document with _extra.id set. Documents are upserted and the full-text search index is rebuilt automatically.

Flags:

Ingesting a New Project Version (ingest)

Catalog a new project version from a local exo bundle directory:

exo standalone ingest ./my-bundle --project-id myproject --version v1.0.0

<bundle-dir> must be a directory in the exo bundle format (bundle.json plus per-file .json metadata files). The server computes all _extra fields (id, gprn, tenant, permissions, latest).

Flags:

On success, the server returns the job ID:

{
  "job_id": "..."
}

Typical Workflow

# 1. Start the stack
exo standalone up --secret-key mysecret &

# 2. Check it is healthy
exo standalone status

# 3. Load an existing snapshot
exo standalone seed snapshot.ndjson

# 4. Ingest a new project version
exo standalone ingest ./bundle --project-id myproject --version v1.0.0

# 5. Stop the stack
exo standalone down

Environment Variable