// documentation · toolkit v5
DevNexus Docs
Everything you need to install, configure and ship with the DevNexus toolkit. Guides assume nothing; references assume everything.
01 · getting started
Getting started
The DevNexus toolkit is one CLI (devnexus) that installs and manages four products:
NexusTrace,
DriftAPI,
ForgeKit and
Relay CLI.
You can adopt the whole toolkit or a single product — everything is local-first and works without an account.
The init command writes a devnexus.yaml to your repo root,
detects your languages and frameworks, and suggests sensible defaults. Nothing is uploaded anywhere.
tip
Run devnexus doctor at any point to validate your setup — shell, PATH, agent versions and certificates.
02 · installation & requirements
Installation & requirements
Requirements are deliberately boring: a shell, and Node 18+ only if you use the npx installer.
$ curl -fsSL https://get.devnexus.dev/install | sh
$ devnexus --version
devnexus 5.4.0 (linux-amd64, musl)
PS> irm https://get.devnexus.dev/install.ps1 | iex
PS> devnexus --version
devnexus 5.4.0 (windows-amd64)
| macOS | 12+ (arm64, x64) | ✓ supported |
| Linux | glibc 2.31+ / musl (x64, arm64) | ✓ supported |
| Windows | 10+ (x64), WSL2 recommended | ✓ supported |
| Docker | ghcr.io/devnexus/toolkit:5 | ✓ official image |
03 · your first trace
Your first trace
Instrument a service in one import, generate traffic, then inspect the trace in your terminal. Four minutes, start to finish.
Step 1 — add the agent
Step 2 — instrument your entrypoint
import "nexustrace/register"; // first line, before everything
import { app } from "./app";
app.listen(3000);
Step 3 — generate traffic & inspect
$ curl localhost:3000/v1/charges -X POST -d @sample.json
$ nexustrace list --last 1
a91f3c2 · POST /v1/charges · 212ms · 6 spans
$ nexustrace inspect a91f3c2 --flame
✓ flame graph rendered — fraud-scorer is your bottleneck (94ms)
Next: sampling rules as code and contract testing with DriftAPI.
04 · api reference
API reference
The DevNexus control API is contract-first: every SDK is generated from the public OpenAPI document below with ForgeKit.
- GET
/v1/tracesList traces. Filter by service, duration, status. - GET
/v1/traces/:idFetch a full span tree with attributes. - POST
/v1/contracts/checkRun a drift check against a base contract. - GET
/v1/sdks/:name/releasesList generated SDK releases and checksums. - POST
/v1/webhooksRegister a signed webhook subscription.
Client libraries: official SDKs for 6 languages, community SDKs for 6 more.
05 · configuration
Configuration
All configuration lives in devnexus.yaml at your repo root — commit it, review it, diff it.
toolkit: v5
trace:
exporter: local # or otlp
sampling: rules/trace.rules.yaml
drift:
contracts: api/contracts/*.yaml
policy: strict
relay:
vault: encrypted
tunnel_domain: relay.devnexus.dev
- ✓ Environment variables override any key: DEVNEXUS_TRACE_EXPORTER=otlp
- ✓ Per-branch overrides for Relay: .relay/env.branch.yaml
- ✓ Secrets never live in devnexus.yaml — use the encrypted vault
06 · troubleshooting
Troubleshooting
? No traces appear after instrumentation
Confirm "nexustrace/register" is the very first import in your entrypoint, then run devnexus doctor. Most misses are transpilers stripping the import — add it to your bundler’s side-effect list.
? Drift check passes locally but fails in CI
Your CI checkout is shallow. Drift needs the base ref: fetch with depth 2 or set drift.base to an explicit SHA in devnexus.yaml.
? Relay tunnel URL rotates on restart
Pin a subdomain with relay tunnel 3000 --sub my-feature. Pinned subdomains are stable for the lifetime of the branch.
? Generated SDK fails my linter
ForgeKit reads your lint config by default. For custom rules, add a lint hook under forgekit.post_generate in devnexus.yaml — see the ForgeKit template docs.
Still stuck? devnexus doctor --report bundles logs & versions into a shareable archive.