Install and authenticate

Install the SDK. The distribution is published as epistabase; the import package is biolake (use import biolake as bl in code):

pip install epistabase

Add optional extras when you need them:

pip install "epistabase[cli]"     # the epistabase command-line interface
pip install "epistabase[image]"   # numpy/pillow for image-region reads

Requires Python 3.12 or newer.

Sign in with the CLI

epistabase auth login --token <PAT> --workspace <workspace-id>

Create a Personal Access Token under Settings → Developer. auth login targets the hosted EpistaBase API by default (https://app.epistabase.com) and validates the token before saving, so a wrong token or URL fails immediately. For a self-hosted deployment, pass --api-url https://<your-epistabase-url>. Check what was resolved with epistabase auth status.

Credentials are written to ~/.epistabase/credentials.json (owner-only) and are picked up automatically by both the CLI and the Python SDK.

Environment variables

Notebook kernels receive a scoped context automatically. For approved scripts outside a managed notebook, use the API URL and token provided by your workspace admin:

export BIOLAKE_API_URL="https://<your-epistabase-url>"
export BIOLAKE_PAT="your-token"
export BIOLAKE_WORKSPACE_ID="workspace-id"
export BIOLAKE_EXPERIMENT_ID="experiment-id"   # optional

Inside managed kernels, the token variable is usually BIOLAKE_TOKEN and may include BIOLAKE_TOKEN_REFRESH_URL.

First check

import biolake as bl

tables = bl.list_tables()
assets = bl.assets(limit=10)

If this fails, check the API URL, token, and workspace ID first.

Security model

The SDK sends authenticated requests to EpistaBase APIs. It does not read AWS credentials or direct S3 keys from your environment. Whole-blob and image reads go through governed access services.