Skip to content

Installation

This page shows how to install the Dox CLI, make a new project and start the server.

Dox needs Dart 3.13 or newer.

Install the CLI

The dox CLI makes projects, runs the server and makes files for you. Install it with pub:

dart pub global activate dox

Check that it works:

dox version

dox: command not found

The shell can not find the CLI, because the pub bin folder is not in your PATH. Add this line to ~/.bashrc or ~/.zshrc, then open a new terminal:

export PATH="$PATH":"$HOME/.pub-cache/bin"

Create a new project

Use dox create with the name of your app:

dox create new_blog

It downloads the newest release of dox-sample, the starter project. To get one exact release, add --version with a release tag of dox-sample.

It also makes your .env file from .env.example, with a new random APP_KEY. Then get the packages:

cd new_blog
dart pub get

The starter project uses SQLite, so there is no database to install. The file db/dox.sqlite is created at the first start. To use Postgres or MySQL instead, change DB_CONNECTION and the DB_* values in .env. See Database.

Add Dox to an existing Dart project

If you already have a Dart project, add the packages you need with dart pub add:

dart pub add dox_core dox_orm dox_migration
dart pub add dev:dox_builder dev:build_runner

Start the server

Start the server in dev mode:

dox s

dox s does two things:

  • It runs dart run bin/server.dart. When you change a file in lib/app/, it hot reloads the new code, so no restart is needed. For routes, providers, config and other start-up code, it restarts the server.
  • It runs dart run build_runner watch, so generated files stay up to date.

At each start it also runs the new migrations in db/migration. The server uses the port in APP_PORT in the .env file (3000 by default). Check that it works:

curl localhost:3000/ping
pong

These options change dox s:

  • dox s --ignore-build-runner skips the builder.
  • dox s --no-reload turns hot reload off.

To start the server without the CLI, run dart run bin/server.dart.

Start the server with Docker

The starter project has a Docker setup. This starts the app, a queue worker and a Postgres database:

docker compose up -d --build

The app and the worker always use the Postgres service. They set DB_CONNECTION and DB_NAME themselves. The database port is open on this machine only (127.0.0.1), not on the network.

If you want only the database in Docker, and the app with dox s, run docker compose up -d postgres. Then set DB_CONNECTION=postgres and DB_NAME=dox in .env.

Production

Do not use dox s or dart run in production. Build a native binary with dox build. See Deployment.

Run the code generator

Dox makes code for models and DTOs with build_runner. dox s already runs it. To run it alone:

dox build_runner:watch   # runs again on every file change
dox build_runner:build   # runs once

AI agents

If you use an AI coding agent, it should know the real API of each package. The Dox packages ship skills for this. Install them in your app, after dart pub get:

dart run skills@ get

It finds the skills of your dependencies and installs them for your agent. It works with Claude Code, Codex, Cursor, GitHub Copilot and others. Run it again after you add a package or update one.

It only reads the packages listed in your own pubspec.yaml. To get the skill of a package that comes in through another one (like ioredis), add it to pubspec.yaml. See skills for the options.

The starter project also has an AGENTS.md file with the rules of the project.

Packages

Dox is split into packages, so you add only what you need:

Package What it does
dox the CLI
dox_core HTTP server, routing, requests, responses, validation
dox_orm query builder and models
dox_migration database migrations
dox_auth Login with access tokens, JWT or sessions
dox_builder, dox_annotation code generation for models, DTOs and the container
dox_validation typed validation schemas
dox_openapi OpenAPI docs
dox_storage file storage: local, S3
dox_cache cache: memory, file, Redis
dox_cache_database cache in a database table
dox_socketio Socket.IO server
dox_queue background jobs
dox_queue_database queue in a database table
dox_scheduler scheduled tasks
dox_mailer send email
dox_view HTML views
dox_inertia Inertia.js pages
dox_http_native native HTTP server (Rust)
dox_postgres_native, dox_mysql_native native drivers for Postgres and MySQL/MariaDB