Getting started / Reference /
Tasks

Tasks

Overview

Tasks are one-time container executions for running background jobs, database migrations, administrative scripts, interactive console sessions, and other ad-hoc operations. Unlike processes (which run continuously), tasks run to completion and then terminate.

Purpose and Benefits

  • Isolated Execution: Each task runs in its own container with a clean environment
  • Resource Control: Configurable CPU, memory, and execution time limits
  • Interactive Sessions: Support for live interactive console sessions (e.g. bash, rails console)
  • Audit Trail: Complete history of all task executions and their logs
  • Flexible Execution: Use your app’s Docker image or any custom image

CLI Usage

Create Background Task

Run a one-off non-interactive background task in an ephemeral container with the given command

tapit create task 'background command here' [-w|--wait] [memory|cpu|docker_tag|image|max_hours|initiated_by|ephemeral_storage_gb]=value

Arguments

  • ‘background command here’ - The command to run in the container

Parameters

  • memory: Memory allocation in GB (default: 2)
  • cpu: CPU allocation in vCPUs (default: 1)
  • docker_tag: Docker image tag to use (optional, overrides latest deployed)
  • image: Custom Docker image URI to use (optional, overrides docker_tag)
  • max_hours: Maximum runtime in hours before the task is killed (default: 48)
  • initiated_by: Name of the person or system that initiated the task
  • ephemeral_storage_gb: Ephemeral storage size in GB (default: 20)
  • -w|--wait: Wait for the task to finish and stream its exit status

Examples 

# Run a database migration
tapit create task 'rails db:migrate'

# Run with explicit resource allocation
tapit create task 'python scripts/process_data.py' memory=4.0 cpu=2.0

# Run and wait for completion
tapit create task 'bundle exec rake data:import' --wait

# Run with a specific image tag
tapit create task 'rails db:seed' docker_tag=v1.2.3

# Run with a time limit
tapit create task 'python long_running_job.py' max_hours=6

# Run a command using a public Ubuntu image
tapit create task 'apt-get install -y curl && curl https://example.com/report' image=ubuntu:24.04

Run Interactive Console

Launch an interactive CLI-based terminal console session inside an ephemeral container

tapit run 'bash' [local|memory|cpu|docker_tag|image|max_hours|ephemeral_storage_gb]=value

Arguments

  • ‘bash’ - The shell or command to open in the container

Parameters

  • local: Run the session locally instead of in the cloud (local dev only)
  • memory: Memory allocation in GB
  • cpu: CPU allocation in vCPUs
  • docker_tag: Docker image tag to use
  • image: Custom Docker image URI to use
  • max_hours: Maximum session duration in hours
  • ephemeral_storage_gb: Ephemeral storage size in GB (default: 20)

Examples 

# Open a bash shell
tapit run 'bash'

# Open a Rails console
tapit run 'rails console'

# Open a Python interactive session
tapit run 'python'

# Open console with more memory
tapit run 'bash' memory=2.0

Show Task Details

Show details and logs for a specific task

tapit show task task=<task_name>

Parameters

  • task: Name of the task to show (required)

List Tasks

List background tasks for the app with their state and exit reason

tapit list tasks [-all] [from=iso8601] [to=iso8601] [interval=1h|4h|12h|24h|3d|7d|14d] [limit=n]

Parameters

  • from: Start of the time range with -all (ISO8601 timestamp)
  • to: End of the time range with -all (ISO8601 timestamp, defaults to now)
  • interval: Named interval instead of from/to with -all, eg. 4h, 24h, 7d
  • limit: Maximum number of tasks to list (default 50)
  • -all: Include already completed historic tasks. Without this means only currently running tasks are shown.

Delete Task

Stop and delete a running or completed task

tapit delete task task=task_name

Parameters

  • task: Name of the task to delete (required)

View Task Logs

Task logs can be viewed via the logs command:

# View logs for a specific task
tapit show logs task=<task_id>

Task Types

Background Tasks

Created with create task. Run asynchronously to completion. Useful for:

  • Database migrations
  • Data import/export scripts
  • Batch processing jobs
  • One-time administrative operations

Console Sessions

Created with run. Provide an interactive terminal session. Useful for:

  • Debugging and investigation
  • Running application consoles (Rails, Django shell, etc.)
  • Manual data fixes
  • System inspection

Resource Defaults

Tasks inherit default resource settings from your app configuration. You can override these per-task:

  • Memory: Default from app settings (typically 0.5 GB)
  • CPU: Default from app settings (typically 0.25 vCPUs)
  • Max Hours: No limit by default

Copying Files Into and Out of Containers

You can copy a file into a container like this:

( echo 'cat > /path/to/file' ; cat local_filename ) | tapit run bash image=utility

And out again:

tapit run 'cat /path/to/file' image=utility > local_filename

This could be useful for eg. copying files quickly into and out of an EFS mount.

Best Practices

  • Always specify --wait for critical operations like migrations to ensure completion
  • Use max_hours for long-running jobs to avoid runaway tasks
  • Use initiated_by to track who launched tasks in audit logs
  • Check task logs promptly after completion for error detection