Installation & Activation

This page covers installing the OmicsBox Engine and getting your account ready to run cloud analyses.

Installing the Engine

Installation packages

The OmicsBox Engine will be distributed as native packages for the major desktop and server platforms:

• Linux — .deb (Debian/Ubuntu) and other common package formats.
• Windows — .exe installer.
• macOS — to be confirmed.

Each installer will place the omicsbox command on the system PATH and set up shell auto-completion. Per-platform steps will be added here when the packages are released.

Shell auto-completion

The Engine ships a shell completion script for bash and zsh. The installers will enable it automatically.

Licensing and subscription

The OmicsBox Engine uses your OmicsBox subscription. Details of how the license applies to the Engine — including whether it is licensed separately from the desktop application, which modules are covered, and how Cloud Units are consumed — will be documented here.

During development

Ahead of the packaged release, the Engine is built from source and run through a temporary launch script. This path is for internal testing only and is not a supported installation method.

Activation and sign-in

Most OmicsBox Engine tools run on OmicsCloud, so before running them you need to activate your subscription once and sign in to your OmicsCloud account. The Engine keeps its credentials separate from the desktop application, so signing in on one never disturbs the other.

Commands that only read local information — list, describe, version, config, whoami and export — work without activation or sign-in. Anything that reaches the cloud (any cloud analysis, plus status, logs, cancel and cloud-files) requires both.

One-time setup

omicsbox activate <your-45-character-subscription-key>

activate validates your subscription key against the OmicsBox servers and, on success, automatically continues into the browser sign-in flow — so this single command normally leaves you ready to run cloud tools. It opens your system browser to sign in to OmicsCloud and waits for you to complete the login.

After setup, confirm your status at any time:

omicsbox whoami

whoami reads your local activation and sign-in state (it makes no network calls) and prints your signed-in email, your active modules, and a masked subscription key.

Activating without signing in

On a headless server, in a script, or whenever you want to defer the browser step, activate the key only and sign in later:

omicsbox activate <key> --no-login    # persist the key, skip the browser sign-in
omicsbox login                        # sign in when convenient

If you are on a machine without a browser, omicsbox login --no-browser prints the sign-in URL for you to open elsewhere, and --timeout <seconds> adjusts how long it waits (default 300).

Automatic sign-in during activate is also skipped — with a reminder to run omicsbox login — when you use --output-format json or when a valid sign-in already exists on the machine.

Signing out

omicsbox logout                # remove the sign-in; keep the subscription key
omicsbox logout --forget-key   # also remove the subscription key (full reset)

After logout, your subscription key is retained so a later omicsbox login needs no re-activation. --forget-key clears the key as well, returning the machine to a clean state that requires both activate and login again.

The subscription key

The subscription key is the same 45-character key used by the desktop application. The Engine resolves it in this order:

1. the OMICSBOX_SKEY environment variable, if set;
2. otherwise the key saved on disk by omicsbox activate.

Setting OMICSBOX_SKEY is the convenient way to supply the key in CI systems and containers, where it can be injected as a secret instead of running activate interactively.

For the full option list of each command mentioned here, see Built-in Commands.