the-omics-os/lobster/lobster-use

Lobster AI Usage Guide

Describe the biological task in natural language. Lobster routes it to installed specialist agents; do not assume every domain package is installed.

The local interface can run in easy Simplified Chinese: lobster --lang zh, LOBSTER_LANG=zh, or /lang zh inside a session. Command names stay English. With Chinese selected, the assistant is asked to answer in Chinese and to keep tool names, paths, gene symbols, and code in English. See language.

Choose the Correct Client Before Installing

An Omics-OS Cloud account does not mean a Cloud session. If the request is to set up Lobster AI locally using that account, install the Python `lobster-ai` engine and configure its omics-os inference provider. Installing or logging in with npm alone does not install or configure the local Python engine.

For a local setup request, follow the Python setup below. Use the npm route only when the user actually requests managed Cloud sessions; ask if the execution location is unclear rather than guessing from the word "Cloud". Local chat uses Go TUI with a classic terminal fallback; npm Cloud chat uses Ink.

When both clients are installed, check which lobster. npm lobster init is a Cloud onboarding wizard, not local Python setup. In a Python environment, use uv run python -m lobster <command> to address the Python engine explicitly. An npm lobster-cli cloud status result does not establish that Python is installed or that its local provider is configured.

Requirements and Permission Boundaries

• Local engine: Python 3.12+, an installed lobster-ai and relevant domain packages.
• Local inference: choose a configured provider. Examples: ANTHROPIC_API_KEY,

GOOGLE_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, NEBIUS_API_KEY; Bedrock uses AWS_BEDROCK_ACCESS_KEY + AWS_BEDROCK_SECRET_ACCESS_KEY; Azure uses AZURE_AI_ENDPOINT + AZURE_AI_CREDENTIAL. Ollama requires a running local model rather than an API key.

• Local Python with an Omics-OS Cloud account: use an authorized gateway key;

Python's credential environment name is OMICS_OS_API_KEY.

• Managed Cloud sessions: use npm @omicsos/lobster and its login flow.

npm's headless API-key environment name is OMICSOS_API_KEY (different spelling).

• Optional: NCBI_API_KEY for NCBI access.
• Obtain permission before installation, credential writes, downloads, paid

inference, or operations outside the user's chosen workspace. Never print keys.

Local data is stored in the chosen workspace, but local mode is not an offline or no-network promise: remote inference can send prompts and data context to the selected provider, and searches/downloads use external services. Review the data and provider policy before analyzing sensitive material.

Local Python Setup with an Omics-OS Cloud Account

The non-interactive Cloud init flags below require Lobster AI 1.2.2 or later. Use [full] for the default analysis install, not a provider-only/core-only install that can leave no specialist agents. [full] is a bundle, not every optional domain; check the agents needed for the task. If uv is absent, obtain permission to install it first; do not switch to npm or bootstrap with bare pip.

For a fresh approved project/environment (POSIX example):

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python 'lobster-ai[full]~=1.2.2'
.venv/bin/python -m lobster --version

Do not replace an existing .venv without permission. In an already approved Python environment, reuse its interpreter instead. These explicit Python commands avoid a Python/npm binary collision. A uv tool install is another option in the CLI reference.

Get an authorized key from https://app.omics-os.com/account through the human account owner. For machine setup, prefer a securely injected OMICS_OS_API_KEY. If the user instead supplies a key file, set OMICS_OS_KEY_FILE to that authorized path and use export OMICS_OS_API_KEY="$(<"$OMICS_OS_KEY_FILE")" in Bash; do not print it, source the file as code, or enable shell tracing.

(
  set -e
  umask 077
  : "${OMICS_OS_API_KEY:?Supply an authorized Omics-OS Cloud API key securely}"
  .venv/bin/python -m lobster init --non-interactive --use-omics-os \
    --skip-extras --skip-ssl-test </dev/null
  .venv/bin/python -m lobster status
  .venv/bin/python -m lobster agents list
)

This selects the local gateway provider without requiring an Anthropic, OpenAI or personal AWS key. No npm install/login is needed. --use-omics-os looks up the nonblank Python environment key, then the active saved Python platform profile. If neither supplies a usable credential, workspace-mode init tries CWD .env, then global Python credentials.env; --global skips the CWD file. See the lookup details. --omics-os-key <key> takes precedence, including explicit blank input failing without fallback, but can expose the key in process arguments. Do not combine Cloud setup with another provider's flags: the other explicit provider takes priority. --cloud-key is a different legacy supplement, not gateway selection.

Read the exit status and output. Missing credentials fail nonzero without a hidden prompt. Existing different-provider configuration requires approved --force; "already configured" means no rewrite, not a new key rotation or an authentication check. --force can replace credentials and creates a configuration backup; see the write/overwrite details. Do not call internal credential/config APIs to bypass an unsupported CLI; check init --help and upgrade the Python install with permission instead.

Saved, not checked: init persists configuration but does not verify account access, key validity or inference. In Python status, inspect Initialization, Provider and Configuration Source: expect provider omics-os, but Account Access: Not checked (configuration only) is not authentication proof. --skip-extras --skip-ssl-test skips init's optional installs/SSL test, not all possible network activity (a saved OAuth token may refresh). Inspect the agent inventory; "No agents installed" is not an analysis-ready setup. Stop on an unexpected provider, missing task agents or setup errors.

For environment-only local setup, omit init and supply both LOBSTER_LLM_PROVIDER=omics-os and OMICS_OS_API_KEY securely. This does not persist provider credentials. Workspace/global provider settings outrank the provider environment variable; use a clean approved configuration or an explicit --provider omics-os on a later query/chat, not a silent config overwrite.

A human can use Python lobster init and paste a key in the masked Cloud prompt. The npm device flow is a human-approved alternative for managed Cloud sessions, not non-interactive Python setup; configure Python separately. See CLI setup details.

Optional live verification requires separate permission: config-test --json invokes a paid LLM test, may contact NCBI and writes a workspace probe. If approved, use the Python command, require exit 0, JSON valid: true and checks.llm_provider.provider: "omics-os", and retain failure diagnostics privately. Do not run it merely to claim setup success.

Local Analysis Example — After Approved Setup

The examples below assume lobster resolves to Python. In the .venv above, replace it with .venv/bin/python -m lobster (or use the activated environment). Downloads and paid inference require their own permission, not just setup consent.

# Teaching dataset; download and inference also require permission
WORKSPACE="./pbmc3k"
mkdir -p "$WORKSPACE/data"
curl -fL -o "$WORKSPACE/data/pbmc3k.tar.gz" \
  https://cf.10xgenomics.com/samples/cell/pbmc3k/pbmc3k_filtered_gene_bc_matrices.tar.gz
tar -xzf "$WORKSPACE/data/pbmc3k.tar.gz" -C "$WORKSPACE/data"
WORKSPACE="$(cd "$WORKSPACE" && pwd)"
 
# Load and assess in ONE query; do not assume a later query retains QC state
lobster query -w "$WORKSPACE" --session-id pbmc3k --json \
  "Load the 10x matrix in $WORKSPACE/data/filtered_gene_bc_matrices/hg19
   (matrix.mtx, genes.tsv, barcodes.tsv; human PBMCs, hg19) as pbmc3k.
   Use gene symbols as var names. Report the loaded shape, then assess quality:
   per-cell genes, total counts and percent mitochondrial (MT- genes), with
   medians and 95th percentiles from tools. Do not filter or run DE."
lobster command "workspace list" -w "$WORKSPACE" --session-id pbmc3k --json

PBMC 3k's local 1.2.1 load was checked at 2,700 cells × 32,738 genes. This one-query load/QC request is an illustrative agent-drivable combination, not an additional executed acceptance run. The checked 1.2.1 workflow used separate requests in one human chat, explicit /save and a restart check; that evidence is not query-to-query memory persistence or population-level DE.

-w names the workspace root itself: do not append another .lobster_workspace when inspecting outputs. Without an override, the local workspace defaults to ./.lobster_workspace (or LOBSTER_WORKSPACE).

Local Session History Is Not a Data Save

Each lobster query invocation starts a new client. Reusing the workspace and --session-id can restore conversation history, but session JSON does not carry the previous process's in-memory modalities into the next command. A completed query, a session JSON file or an answer written with --output is not proof that analysis data was saved.

Saved inputs: local startup scans <workspace>/data/ for supported files; size/read guards can prevent loading. A later query can load saved *_raw.h5ad or DE-result H5ADs under their file-stem names, not unsaved QC-assessed state. Inspect current files and modalities. When an input is absent, ask the Data Expert to verify its file path/adapter and call load_modality within the query that uses it. A separate inspection/load command does not keep a live client for the next query.

Query-mode saves: some tools write files during a query. GEO imports can write *_raw.h5ad and call autosave at import time; that is not a universal save of changes made later in the query. assess_data_quality creates a QC-assessed modality in memory without saving it. run_de_with_formula(..., save_results=True) can write its result table and H5AD modality. run_bulk_de_direct(..., save_result=True) also has a native save option, but its default marker-style out-group filter can remove most or all bulk genes; prefer the formula tool for an approved bulk design. export_de_results separately writes a table. These saves do not promise every intermediate or every analysis tool's output was written.

Local H5AD save outcomes: a failure before the new file replaces an existing file keeps the previous file. If replacement completed but save bookkeeping fails, the error says the data was saved and bookkeeping failed; inspect the reported file before retrying. This does not save other memory-only outputs.