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:
Check that it works:
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:
Create a new project
Use dox create with the name of your app:
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:
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:
Start the server
Start the server in dev mode:
dox s does two things:
- It runs
dart run bin/server.dart. When you change a file inlib/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:
These options change dox s:
dox s --ignore-build-runnerskips the builder.dox s --no-reloadturns 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:
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:
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:
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 |