sw-agent-dokku

The sw-agent-dokku command scaffolds, deploys, and manages SignalWire agent projects on Dokku. It generates Dokku-ready project structures with Procfile, runtime configuration, health checks, and optional GitHub Actions CI/CD workflows.

sw-agent-dokku <command> [options]

Commands

Create a new Dokku-ready agent project.

sw-agent-dokku init <name> [options]

name

stringRequired

Project/app name. Used as the Dokku app name and directory name.

--cicd

flag

Include GitHub Actions CI/CD workflows for automated deployment on push and preview environments for pull requests.

--web

flag

Include a web interface with static file serving at the root route. Adds WebRTC calling support with dynamic token generation.

--host

string

Dokku server hostname. If provided, configures the git remote during init.

--dir

string

Parent directory for the project.

--force, -f

flag

Overwrite an existing directory.

Generated Structure

myagent/
  app.py              # Agent entry point (gunicorn-compatible)
  Procfile            # Dokku process definition
  runtime.txt         # Python version (3.11)
  requirements.txt    # Dependencies
  CHECKS              # Health check configuration
  .env.example        # Example environment variables
  .gitignore
  README.md

When --web is specified, the project includes a web/ directory with static files and WebRTC calling support. When --cicd is specified, a .github/workflows/ directory is added with deployment and preview environment workflows.

Deploy the current directory to Dokku via git push.

sw-agent-dokku deploy [options]

--app, -a

string

App name on the Dokku server. Auto-detected from the git remote if not specified.

--host, -H

string

Dokku server hostname.

View application logs from Dokku.

sw-agent-dokku logs [options]

--app, -a

string

App name.

--host, -H

string

Dokku server hostname.

--tail, -t

flag

Tail logs in real time.

--num, -n

int

Number of log lines to display.

Manage environment variables on the Dokku app.

sw-agent-dokku config <action> [vars...] [options]

config_action

stringRequired

Config action. Valid values:

"show" — Display all config variables
"set" — Set one or more variables (KEY=value)
"unset" — Remove one or more variables

vars

string

Variables in KEY=value format (for set) or variable names (for unset).

--app, -a

string

App name.

--host, -H

string

Dokku server hostname.

Scale Dokku process types.

sw-agent-dokku scale [scale_args...] [options]

scale_args

string

Scale arguments in process=count format (e.g., web=2).

--app, -a

string

App name.

--host, -H

string

Dokku server hostname.

Examples

Initialize a project

sw-agent-dokku init my-agent --web --cicd --host dokku.example.com

Deploy

cd my-agent
sw-agent-dokku deploy

View logs

sw-agent-dokku logs -t

Manage config variables

sw-agent-dokku config set SWML_BASIC_AUTH_PASSWORD=secret123 PORT=3000
sw-agent-dokku config show

Scale processes

sw-agent-dokku scale web=2

Full workflow

# 1. Create a Dokku-ready project with web UI and CI/CD
sw-agent-dokku init my-agent --web --cicd --host dokku.example.com
# 2. Configure environment variables
cd my-agent
sw-agent-dokku config set \
  SWML_BASIC_AUTH_PASSWORD=secure-password \
  SIGNALWIRE_SPACE_NAME=my-space \
  SIGNALWIRE_PROJECT_ID=my-project-id \
  SIGNALWIRE_API_TOKEN=my-token
# 3. Deploy
sw-agent-dokku deploy
# 4. Monitor
sw-agent-dokku logs -t

SIGNALWIRE_SPACE_NAME configures the CLI and the deployed app’s dashboard links. If the agent also uses RestClient or RelayClient, set SIGNALWIRE_SPACE to the full hostname, my-space.signalwire.com, in the same config set call.