How to Use Deriv One: The Beginner's Guide

CodexFuse Team · 2026-11-02T14:49:43.021Z · 13 min read min read

Deriv One is the self-hosted enterprise AI platform the online broker Deriv built for itself — this beginner's guide covers the install, model gateway, skills catalog, agent registration, and governed deployment.

Deriv One is the self-hosted enterprise AI platform that the online broker Deriv built for its own teams — and on October 30, 2026, Deriv open-sourced it under the MIT license. If you want to know how to use Deriv One, here is the short version: you clone the repository, run a setup wizard that points the platform at a model gateway, start the stack, and land in a governed chat workspace where a versioned skills catalog, registered AI agents, and a no-code app builder all sit behind company-grade access control. It is not another chatbot wrapper; it is the infrastructure a whole company shares when everyone needs AI with guardrails. This tutorial walks the complete beginner path: the mental model that makes Deriv One click, the install, the model gateway, the skills catalog, agent registration, the governance layer, and the Docker and Kubernetes deploy options. Because Deriv One is software you host yourself, what VPS hosting is is the right background concept — the platform assumes you have a machine to run it on, whether a cloud server or a box in your office.

What Is Deriv One, Exactly?

Deriv One is a self-hosted AI platform: an editor-style, multi-pane chat workspace with a versioned skills catalog, AI agent registration, and a no-code app builder — all governed by role-based access and sandboxed code execution.

One clarification up front, because search engines mix the names: Deriv One is not the Derive Protocol. Derive (formerly Lyra) is a decentralized on-chain options exchange; Deriv One is the AI platform of Deriv, the online trading broker whose own press boilerplate says it has spent over 26 years making online trading accessible and is trusted by over 3 million traders worldwide. The platform was announced on October 21, 2026 (reported by TokenPost) and open-sourced on October 30 (reported by FX News Group), which is why you will still find almost no independent how-to coverage — this guide is written against the repository as it exists today.

The mental model that makes everything else click: Deriv One began as a skills registry. Every team's skills live in one catalog, access is tied to job functions, agent permissions are reviewed, and model-generated code runs sandboxed. If you hold that picture — a governed registry, not a chatbot — every screen in the product makes sense.

As of November 2, 2026, the official repository is github.com/deriv-com/deriv-one-oss: public, MIT-licensed, default branch master, with 7 stars, 4 forks, 17 commits, last pushed November 1, created August 31 — and zero releases so far. Those numbers move; verify them before you quote them.

How Do You Use Deriv One, Step by Step?

Seven steps take you from an empty machine to a governed workspace: clone the repository, install the dependencies, configure the environment, run the setup wizard, start the stack, connect a model gateway, and register your first agent.

Clone the repository. Run git clone https://github.com/deriv-com/deriv-one-oss.git and cd deriv-one-oss. (Caution: the launch press printed cd platform — that directory does not exist; the real checkout directory is deriv-one-oss.)
Install the dependencies. In backend/, create a Python 3.12 virtual environment and install requirements.txt; at the repo root, run npm install with Node.js 20 or newer.
Configure the environment. Copy backend/.env.example to backend/.env — or let the setup wizard write backend/platform.env for you in the next step.
Run the setup wizard. npm run setup -- --quick --test-gateway configures the gateway, the encryption key, and the auth mode, and can probe your model gateway before anything starts.
Start the stack. npm run dev:stack brings up the dev UI at http://localhost:3000 (it proxies the API to port 8000), and mock auth signs you in as the admin user from the environment.
Connect a model gateway and browse the skills catalog. Point the platform at any OpenAI-compatible gateway — a local stack or a cloud gateway you control — then open the catalog and see which skills your role can use.
Register your first agent and review the access grant. Give it a name, a persona, a model, and a set of skills; then watch the governance layer decide what it may touch.

What Do You Need Before You Install?

Four things stand between you and a running stack: a model gateway, Docker, the right runtimes, and a machine to host it all.

Requirement	What to use	Why it matters
Model gateway	Any OpenAI-compatible HTTP API — LiteLLM, vLLM, or a cloud gateway you control; the README notes Ollama needs a proxy	Deriv One ships no model of its own; every turn routes to your gateway
Docker	Docker Desktop or Docker Engine on Linux	Recommended by the README and required for the sandboxed code execution
Runtimes	Node.js 20+ and Python 3.12+	Frontend tooling and the Python backend respectively
A machine you control	A VPS or a local server	The platform is self-hosted — it assumes infrastructure you administer

The Docker row deserves emphasis: Deriv One executes model-generated Python inside disposable containers, so a machine without Docker loses the platform's headline safety feature.

How Do You Install Deriv One?

The README's quick start is a clone, a dependency install, a setup wizard, and one stack command — or a single docker compose up --build if you would rather run containers from the start.

Route	Commands	Best for
Dev path (README)	git clone → venv + pip install → npm install → npm run setup → npm run dev:stack	Developers who want to read and hack the code
Docker path	Set three .env values → docker compose up --build	Teams that want the platform up with minimum fuss

Start with the clone. If you are rusty on the basics, our Git beginner guide covers the workflow the README assumes:

git clone https://github.com/deriv-com/deriv-one-oss.git
cd deriv-one-oss
cp backend/.env.example backend/.env
cd backend && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cd .. && npm install

Then let the wizard do the wiring:

npm run setup -- --quick --test-gateway

The wizard writes backend/platform.env — your gateway choice, the encryption key, and the auth mode — and the --test-gateway flag probes the gateway before the stack starts, which catches a bad key or URL in seconds instead of after a confusing first chat turn.

Finally, start everything:

npm run dev:stack

The dev UI appears at http://localhost:3000, proxying the API to port 8000. Mock auth signs you in as the admin user from the environment, so your first session is already administrative — which is exactly why the governance sections below matter before you invite anyone else.

Prefer containers? Set MODEL_GATEWAY_URL, MODEL_GATEWAY_API_KEY, and SECRET_ENCRYPTION_KEY, then run docker compose up --build. If Docker itself is the unfamiliar part, our Docker beginner guide walks through the concepts the compose file assumes.

How Do You Connect a Model Gateway?

Set MODEL_GATEWAY_URL and MODEL_GATEWAY_API_KEY in backend/.env — or answer the setup wizard's gateway questions — then adjust the models later at Settings, Platform setup (/admin/setup) after your first login.

For a local gateway running in Docker, the README's .env.example ships the two addresses you will reach for: http://host.docker.internal:4000 on Docker Desktop and http://172.17.0.1:4000 on Linux. The honest framing, matching both the README and the launch press, is "any OpenAI-compatible gateway": LiteLLM, vLLM, and cloud gateways you control all qualify; the README specifically notes Ollama needs a proxy in front of it, and the press names local LM Studio or Ollama as workable endpoints. If you run models locally, our Ollama beginner guide covers the server side of that setup.

One detail worth knowing early: Deriv One runs a complexity router over every turn. It classifies each message — greeting, simple, reasoning, retry-escalation — and routes it to a cheap, fast, or frontier model accordingly, so your gateway configuration directly shapes both the bill and the quality.

What Are Skills in Deriv One?

A skill is a markdown file with frontmatter — a small, versioned, reviewable unit of know-how that teams publish into a shared catalog.

That one sentence carries the whole design. Skills are versioned, reviewed before publication, and visible per person; the access manifest lives in skills_acl.py and src/data/skills-acl.yaml, and the publication pipeline runs an AI security review before a skill goes live. At launch, Deriv said its internal deployment held 221 skills from 54 people — that is the company's own launch figure, not something verifiable in the public repo, but it tells you the scale this design targets.

The workspace around the catalog is editor-style: multi-tab, split-pane chat with an @-mention composer and a context meter, so a "skill" feels less like a plugin and more like a documented capability your whole company can call on.

How Do You Register an AI Agent?

You register an agent with a name, a persona, a model, attached skills, and access grants — and Deriv One isolates it the way you would isolate a new employee.

Registration runs through api_agents.py. Each agent becomes its own Slack app with its own signing secret, and — this is the part that matters for security reviews — each agent invocation runs in its own subprocess that loads only that agent's credentials. One agent's tokens are never in the same process as another agent's.

Permissions follow a default-deny rule. Slack scope inference reads an agent's description, infers the minimum scopes it needs, and adjudicates any extra scope requests against an allowlist. An agent that asks for more than its description justifies does not get it.

What Can You Build With the No-Code Lab?

You describe an app in chat; the Lab classifies it, picks a stack and skills, generates it, builds it, and deploys it to a URL on your instance.

Under the hood, app_classifier.py picks the stack and the skills, api_apps.py generates the app, and node_build.py builds React apps when the job needs them. You iterate in chat with a live preview, then deploy to a URL served by your own instance — nothing leaves your infrastructure. The README marks the Lab's status honestly: Beta — sandbox required, with React and vanilla stacks supported.

How Does Deriv One Govern AI Access?

Three mechanisms do the governing: roles from your identity provider, reviewed agent permissions, and sandboxed code execution. This is the layer that separates Deriv One from a shared chatbot account.

Roles. Roles come from OIDC group claims mapped by ADMIN_GROUPS, MEMBER_GROUPS, and READONLY_GROUPS; ADMIN_EMAILS bootstraps the first admin, and by default any authenticated caller is a member. Access itself flows through a full lifecycle — request, approver, time-bounded grant, expiry warning, revoke, audit trail — implemented in api_access.py and access_models.py. Approvers come from the directory provider; where there is none, requests route to admins.

Reviewed agent permissions. As the registration section showed, agents get minimum scopes inferred from their descriptions, with extra requests adjudicated against an allowlist and denied by default. Skills pass an AI security review before publication.

Sandboxed execution. Model-generated Python runs in disposable containers — image platform/sandbox-python:latest, built from docker/sandbox/Dockerfile — with no network, no credentials, dropped capabilities, a read-only root filesystem, and destruction after each run. The unsandboxed subprocess provider exists but refuses to start without ALLOW_UNSANDBOXED_EXECUTION=1, and gVisor support arrives via SANDBOX_RUNTIME=runsc when the host provides it.

How Do You Deploy Deriv One for a Team?

The repo ships a Helm chart, reference Kubernetes manifests, and Terraform examples — the README points at GKE and EKS for managed Kubernetes.

In the repo layout you will find deploy/helm/platform/ (the Helm chart), deploy/k8s/ (reference Kubernetes manifests), deploy/terraform/ (starter AWS and GCP data-plane examples), and the cloud guide at docs/cloud-deployment.md. For production, swap the dev-time mock auth for a real OIDC or JWT proxy — the prereqs list flags this from the start.

Know what the open release does not include: Deriv's production cloud plugins, internal integrations, and some Lab features are excluded, and adopters bring their own gateway, identity provider, and cloud. That is straight from the launch reporting — plan your deploy around it, not around the internal Deriv deployment.

How Is Deriv One Different From Dify?

Dify is an app builder; Deriv One is a governed skills platform. They sit in different lanes, not as rivals.

Dify helps you build AI applications on top of models — if that is your goal, start with our Dify beginner guide. Deriv One starts from a different question: which skills may which people and agents use, under whose review, with what sandboxed execution? If you want to ship an app fast, the app-builder lane fits. If you want a whole company to share AI safely — one catalog, one access model, one audit trail — that is the governed-skills lane Deriv One was built for.

7 Beginner Mistakes With Deriv One

Every one of these comes from a real trap in the launch materials — the press, the README, or the gap between them.

Mistake	Why it hurts	Do this instead
Following the press snippet's `cd platform`	That directory does not exist; the clone lands in `deriv-one-oss`	Clone, then `cd deriv-one-oss` — trust the README, not the press snippet
Skipping `--test-gateway`	A dead gateway surfaces as confusing chat failures instead of a clean error	Let the wizard probe the gateway before the stack starts
Pointing at Ollama directly	The README says Ollama needs a proxy in front of it	Use any OpenAI-compatible gateway endpoint, or the documented host addresses for Docker
Committing `SECRET_ENCRYPTION_KEY` to git	It protects every stored secret in the platform	Generate it per deployment, keep it in `.env`, rotate it like a password
Setting `ALLOW_UNSANDBOXED_EXECUTION=1` on a shared box	You trade the platform's headline safety feature for convenience	Keep sandboxed execution on any shared machine; use the flag only for local experiments
Treating the catalog like a plugin folder	Unreviewed skills bypass the governance the platform exists for	Publish through the pipeline: versioning, access manifest, AI security review
Expecting Deriv's production plugins	The open release excludes them; the gap surprises teams mid-deploy	Bring your own gateway, identity provider, and cloud from day one

Sources

Deriv One repository (README, install, features, governance, deploy layout) — github.com/deriv-com/deriv-one-oss, fetched November 2, 2026
"Deriv open-sources its self-hosted enterprise AI platform Deriv One" — FX News Group, October 30, 2026 (launch figures, skill counts, excluded production plugins, gateway options)
"Deriv Announces Upcoming Launch of Deriv One" — TokenPost, October 22, 2026 (October 21 announcement)
Deriv press releases listing — deriv.com newsroom, fetched November 2, 2026 (company boilerplate: 26 years, 3 million traders)

Frequently Asked Questions

Is Deriv One free?

Yes — it is MIT-licensed open source, so there is no license cost. Your costs are the infrastructure: the machine that hosts it and whatever your model gateway charges. Note that Deriv's production cloud plugins and internal integrations are excluded from the open release, so plan your own gateway, identity provider, and cloud.

What models can I use with Deriv One?

Any OpenAI-compatible gateway: LiteLLM, vLLM, a cloud gateway you control, or a local endpoint — the README notes Ollama needs a proxy, and the launch press names local LM Studio or Ollama as workable. The setup wizard can probe the gateway before the stack starts.

Does Deriv One need Docker?

Docker is recommended and is required for the sandboxed code execution — model-generated Python runs in disposable containers with no network and no credentials. Without Docker you lose that layer, which is a large part of the platform's point.

Is Deriv One the same as the Derive crypto protocol?

No. Deriv One is the self-hosted AI platform of Deriv, the online trading broker. Derive (formerly Lyra) is a decentralized on-chain options and perpetuals exchange. Same word stem, completely different products.

How many skills does Deriv One ship with?

At launch, Deriv said its internal deployment held 221 skills from 54 people — that is the company's launch figure for its own production instance. The open repository is the platform itself: you grow your own catalog through the versioned, reviewed publication pipeline.