Getting started

10-minute path from zero to a running Arqen application.

Prerequisites

• Rust 1.98+ (edition 2024): install via rustup
• pnpm (for building docs only): install via npm install -g pnpm
• Docker (optional): needed for thingd HTTP mode and arqen up services

Verify your Rust installation:

rustc --version   # should show 1.98 or newer
cargo --version

Install the CLI

From a repository checkout:

cargo install --path crates/arqen --features cli

Or run directly without installing:

cargo install arqen --locked --features cli
arqen --help

Create a project

arqen new hello-api --yes
cd hello-api

This generates:

hello-api/
  Cargo.toml          # current Arqen 0.21 release and selected features
  README.md
  arqen.toml         # runtime configuration
  .env.example       # environment template
  AGENTS.md           # portable project guidance
  rustfmt.toml       # formatting config
  clippy.toml        # lint config
  src/
    main.rs           # entry point
    app/mod.rs        # AppModule (Module trait)

In a terminal, omit --yes to choose HTTP, native Thingd, logging, starter examples, and optional Nice Code setup interactively. See the CLI project generator for all options.

Run the project

arqen dev

The generated application owns startup and shutdown through Arqen. You do not need to create or configure the underlying async runtime in application code.

For automatic Rust reload during development, install cargo watch and define the backend service in arqen.toml as cargo watch -q -x "run --quiet", then run arqen up. The watcher is supervised by arqen up alongside the frontend, preserving Expo HMR and the native single-process Thingd topology. The legacy arqen dev --watch flag is not used for this stack.

Expected output (the version is dynamic in the real CLI):

Arqen v<current-version>
API:    http://127.0.0.1:8888
Health: http://127.0.0.1:8888/health
Docs:   http://127.0.0.1:8888/docs
Agent:  http://127.0.0.1:8888/agent
Storage: memory

Test the endpoints

curl http://127.0.0.1:8888/health
curl http://127.0.0.1:8888/ready
curl http://127.0.0.1:8888/agent
curl http://127.0.0.1:8888/agent/manifest
curl http://127.0.0.1:8888/docs

Lint and test

arqen lint         # check formatting + clippy
arqen test         # run all tests

Add your first module

arqen generate module users

This creates src/users/mod.rs. Register it in src/app/mod.rs:

mod users;

// In AppModule:
fn dependencies(&self) -> Vec<&str> {
    vec!["users"]
}

Add your first tool

arqen generate tool get_user

This creates src/tools/get_user.rs. Register it in your module's register() method:

fn register(&self, ctx: &mut ModuleContext<'_>) -> Result<(), AppError> {
    crate::tools::get_user::register(ctx)?;
    Ok(())
}

Add your first job

arqen generate job send_email

This creates src/jobs/send_email.rs with a JobHandler stub.

Run from the workspace

If you prefer not to install the CLI:

cargo install arqen --locked --features cli
arqen new hello-api

Next steps

For the complete build path, continue with Build an Arqen backend.

• Commands - full CLI reference
• Configuration - environment variables and config files
• Thingd schema - define, validate, and inspect your data contract
• Modules - module composition and lifecycle
• Typed tools - structured tool definitions
• Logging - structured logs, fields, and redaction
• Application hardening - production boundaries
• Durable jobs - background job processing
• Authentication - JWT and API key auth
• Validation - request validation
• Health - health and readiness checks
• Deployment - production deployment
• Examples - code snippets and examples