How DjangoCommand Works

A lightweight runner in your infrastructure, a powerful dashboard in the cloud.

Quick Start

1

Install the runner

pip install djangocommand

Add to your Django project and configure with your API key.

2

Start the runner process

python manage.py djangocommand start [-d]

The runner auto-discovers your commands and connects to the dashboard.

3

Manage from the dashboard

Run commands, set schedules, view history. All from a clean web UI.

Runner Architecture

Your infrastructure, your code: Commands execute on your servers, we just provide the dashboard. The runner only runs commands you approve. All communication is outbound from your servers (no exposed endpoints). No arbitrary code execution, only your management commands.

Architecture diagram: Your Server (Runner) ← HTTPS → DjangoCommand Cloud

What the runner does

  • Discovers management commands in your Django project
  • Polls the dashboard for pending executions
  • Executes the pending commands as subprocesses
  • Streams output back to the dashboard
  • Reports completion status and exit codes

What the runner doesn't do

  • Accept inbound connections
  • Execute arbitrary shell commands
  • Access or transmit your source code
  • Store credentials (API key is the only secret)

Polling vs Wrapper

DjangoCommand uses a polling architecture rather than wrapping your Django process or injecting middleware.

Polling (DjangoCommand)

  • Runner is a separate process
  • No impact on your Django app performance
  • Works with any deployment (Docker, K8s, PaaS)
  • Runner can restart independently
  • No code changes to your Django project

Wrapper/Middleware

  • Runs inside your Django process
  • Can affect request latency
  • Deployment-specific configuration
  • Tied to your app lifecycle
  • Requires code integration

Scheduling

DjangoCommand replaces crontab for your Django management commands.

How it works

  • Define schedules in the dashboard using cron expressions
  • Our scheduler evaluates due schedules every minute
  • When a schedule is due, the dashboard creates a pending execution
  • Your runner picks it up on its next poll
  • If the runner is offline, the execution is marked as missed

Benefits over crontab

  • Visual schedule management (no SSH required)
  • Execution history, logs, and audit trail
  • Failure notifications
  • Easy to disable/enable without editing files

Environments

DjangoCommand uses separate projects for different environments rather than environment switching within a single project.

Recommended setup

  • Production project: Real commands, strict approval, alerts enabled
  • Staging project: Same commands, relaxed approval, optional alerts
  • Development: Run commands locally (no DjangoCommand needed)

Why separate projects?

  • Clear separation of concerns
  • Different API keys per environment
  • Independent execution history
  • No risk of running production commands in staging (or vice versa)
  • Separate access control

Sensitive Output

Metadata-only mode (shipping soon) lets you run commands that shouldn't log their output. You get execution status and timing without storing content.

Use cases

  • Commands that output PII or user data
  • Database exports or dumps
  • Commands that echo secrets during setup
  • Compliance-sensitive operations

Metadata-only mode is configured per command, so you can choose which commands use it. The commands themselves run exactly as they normally would, including producing output. The difference is that this output is never streamed to the dashboard, it does not leave your server.

Deployment

Start the DjangoCommand runner as a background process alongside your Django application.

VPS / Bare Metal

Start the runner in daemon mode before your application server:

python manage.py djangocommand start -d
gunicorn myproject.wsgi

For production, we recommend using systemd or supervisor for proper process management.

Docker Compose

djangocommand:
  image: your-django-image
  command: python manage.py djangocommand start
  environment:
    - DJANGOCOMMAND_API_KEY=${API_KEY}

PaaS (Heroku, Railway, Render)

Add as a worker process in your Procfile or service configuration:

worker: python manage.py djangocommand start

Kubernetes

Run as a separate Deployment or as a sidecar container. The runner needs access to your Django codebase and environment variables.

For more details, see the runner documentation.

Ready to try it?

Get started with a free trial.

Get early access