Skip to main content

Getting Started

This guide is for operators and users who want to install Taskforge and run workflows.

If you want to contribute to Taskforge itself, use docs/Development.md.

10-Minute Path​

If taskforge is already installed, this is the fastest path from zero to first run.

# 1) Initialize and start stack (external datastores)
taskforge init \
  --database-url "postgresql://user:pass@db.example.com:5432/taskforge" \
  --redis-url "redis://redis.example.com:6379"
taskforge status

# 2) Verify auth works
taskforge auth whoami

# 3) Create a minimal workflow definition
cat > /tmp/tf-definition.json <<'JSON'
{
  "input": {
    "apiBase": "https://jsonplaceholder.typicode.com"
  },
  "steps": [
    {
      "key": "fetch_post",
      "type": "http",
      "request": {
        "method": "GET",
        "url": "{{input.apiBase}}/posts/1"
      }
    }
  ]
}
JSON

# 4) Create workflow and run it
taskforge workflow create --name "First Workflow" --definition /tmp/tf-definition.json
taskforge workflow list
# copy workflow ID from list output
taskforge workflow run <workflow-id>

# 5) Inspect execution
taskforge run list <workflow-id>
taskforge step list <workflow-id> <run-id>

What You Need​

  • Docker + Docker Compose
  • A Taskforge CLI binary

Install the CLI​

Choose one method.

Homebrew​

brew tap gentij/taskforge
brew install taskforge

AUR (Arch Linux)​

yay -S taskforge-bin

GitHub Release Binary​

Download the matching release artifact from:

  • https://github.com/gentij/taskforge/releases

Extract taskforge and put it on your PATH.

Initialize Stack​

taskforge init \
  --database-url "postgresql://user:pass@db.example.com:5432/taskforge" \
  --redis-url "redis://redis.example.com:6379"

This creates local config and starts the Taskforge stack (server, worker).

If you want Taskforge to run bundled local Postgres and Redis instead, use:

taskforge init --with-local-datastores

Check status:

taskforge status

Verify auth:

taskforge auth whoami

Run Your First Workflow​

Create a minimal definition:

cat > /tmp/tf-definition.json <<'JSON'
{
  "input": {
    "apiBase": "https://jsonplaceholder.typicode.com"
  },
  "steps": [
    {
      "key": "fetch_post",
      "type": "http",
      "request": {
        "method": "GET",
        "url": "{{input.apiBase}}/posts/1"
      }
    }
  ]
}
JSON

Create and run:

taskforge workflow create --name "First Workflow" --definition /tmp/tf-definition.json
taskforge workflow list
# use workflow id from list output
taskforge workflow run <workflow-id>

Inspect run details:

taskforge run list <workflow-id>
taskforge step list <workflow-id> <run-id>

Optional: Configure Public Webhook Ingress​

Create a webhook trigger and rotate a path key:

taskforge trigger create <workflow-id> --type WEBHOOK --name "Inbound"
taskforge trigger webhook rotate-key <workflow-id> <trigger-id>

This prints a URL in the format:

  • http://<host>:3000/v1/api/hooks/:workflowId/:triggerId/:webhookKey

Use that URL in your webhook provider. For reverse proxy starters, see:

  • deploy/ingress/nginx.taskforge.conf.example
  • deploy/ingress/Caddyfile.example

Optional: Open the TUI​

taskforge tui

Next Steps​