Getting Started

Installation

Install the OXP CLI and set up your development environment in under two minutes.

Getting started with OXP takes less than two minutes. You need Node.js, a package manager, and you're ready to build your first extension.

Prerequisites

Requirement	Version	Notes
Node.js	≥ 22	LTS recommended. Check with `node -v`
pnpm	≥ 10	Or npm / yarn — all work
Git	Any	For version control

OXP extensions can be written in TypeScript (declarative UI, HTML-based) or Rust (WASI components). For Rust extensions you also need:

Requirement	Version	Notes
Rust	stable	Install via rustup
wasm32-wasip2 target	—	`rustup target add wasm32-wasip2`

Install the CLI

The OXP CLI ships as a single npm package. Pick whichever package manager you already have — there is no separate installer to download.

Persistent install (recommended)

npmbash

npm  i -g @oxprotocol/cli

pnpmbash

pnpm add -g @oxprotocol/cli

yarnbash

yarn global add @oxprotocol/cli

After install, verify with:

bash

oxp --version
# 0.1.0

One-shot (no install)

If you just want to scaffold a project without a global install:

bash

npx @oxprotocol/cli@latest create my-ext
pnpm dlx @oxprotocol/cli create my-ext
yarn dlx @oxprotocol/cli create my-ext

npm create shortcut

For scaffolding only, the dedicated create-oxp wrapper plays nicely with the npm create convention:

bash

npm  create oxp@latest my-ext
pnpm create oxp my-ext
yarn create oxp my-ext

Environment Variables

The CLI respects two environment variables for configuration:

Variable	Default	Purpose
`OXP_REGISTRY`	`https://oxp.sh`	Base URL of the OXP registry
`OXP_HOME`	`~/.oxp`	Config + credentials directory

For production use, set the registry to the public instance:

bash

export OXP_REGISTRY=https://oxp.sh

Credentials

When you run oxp login, your API token is stored at ~/.oxp/credentials with mode 0600 (owner-only read/write). The CLI sends it as Authorization: Bearer <raw> on authenticated requests.

You can rotate your token at any time:

bash

oxp token rotate

Setting Up from Source (Contributors)

If you want to contribute to OXP itself, clone the monorepo:

bash

git clone https://github.com/oxp-dev/oxp.git
cd oxp
pnpm install
pnpm build

For local development with a database, spin up Postgres and MinIO:

bash

docker compose up -d
pnpm --filter @oxprotocol/web db:push
pnpm dev

This gives you a local registry at http://localhost:3000 with a Postgres database and S3-compatible object storage.

What's Next

Now that you have the CLI installed, head to Your First Extension to build and run your first OXP extension in under five minutes.