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 

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

Launches a background task that runs to completion.

Required Parameters

  • command: The shell command to run (quoted string, first positional argument)

Optional Parameters

  • --wait: Wait for the task to complete before returning, then stream logs
  • memory: Memory allocation in GB
  • cpu: CPU allocation in vCPUs
  • docker_tag: Specific Docker image tag to use
  • image: Custom container image for this task. When set, the task runs using this image instead of the app’s own Docker image built during deployment. Any image can be used, including external or public images (e.g. ubuntu:24.04, public.ecr.aws/myorg/mytool:latest). This is useful for running utility containers or tools that are separate from your application.
  • max_hours: Maximum execution time in hours before the task is terminated
  • initiated_by: Name/identifier of who or what launched the task
  • ephemeral_storage_gb: Ephemeral storage allocation in GB

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 

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

Launches an interactive console session. The CLI connects to the running container for a live shell session.

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 

tapit  show task task=<task_id>

Displays details about a specific task including its status, resource usage, and logs.

Required Parameters

  • task: Task ID to show details for

List Tasks 

tapit  list tasks

Shows recent task history with status, timing, and resource information.

Delete Task 

tapit  delete task task=id123

Removes a task record from the history.

Required Parameters

  • task: Task ID to delete

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

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
ProcessesConsole Session