Getting started / Reference /
Console Session

Console Session

Overview

A console session is an interactive terminal session that runs inside an ephemeral container. The container spins up with access to all the same add-ons and resources as the app itself (databases, caches, file storage, environment variables, etc.).

For non-interactive jobs that run to completion without a terminal, use tapit create task instead.

CLI Usage

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)

There is no tapit create console command. Use tapit run bash for interactive foreground sessions.

Examples 

# Open a bash shell in the current app
tapit run 'bash'

# Open a bash shell in a specific app
tapit -a my-api run 'bash'

# Open a Rails console
tapit run 'rails console'

# Open a Django shell
tapit run 'python manage.py shell'

# Open a Python interactive session
tapit run 'python'

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

# Open a console using a specific deployed tag
tapit run 'bash' docker_tag=v1.4.2

# Open a console with a time limit (auto-terminates after 2 hours)
tapit run 'bash' max_hours=2

# Open a console using a public image
tapit run 'bash' image=ubuntu:24.04

Running a shell on your app container requires curl and bash to be preinstalled in your app’s container image.

Web UI

The Tasks page provides two buttons for launching console sessions in a web-based terminal:

  • App console: Runs a bash shell inside your app’s container. Your app container must have curl and bash preinstalled for this to work.
  • Utility console: Runs a bash shell using the Tapitalee utilitycontainer image, which is Ubuntu preloaded with commonly needed utilities like mysql, psql, and other database clients. Useful when your app image is minimal or lacks debugging tools.

Both console types can be configured with any docker_tag (for uploaded app container images) or any other container image via the image field.

File Upload and Download

Web UI console sessions include Upload and Download buttons in the terminal toolbar:

  • Upload: Send a local file into the container by choosing (or drag-and-dropping) the file and specifying a destination directory on the server.
  • Download: Browse the container’s file system from a chosen directory, filter the listing, and download any file to your local machine.

File transfer is available only in web UI sessions, not in CLI (tapit run) sessions.

Image Selection

Both console and background tasks can run with any specified docker_tag for uploaded app container images, or any other container image via the image field.

Behaviour

  • Ephemeral: The container is created fresh for the session and destroyed when you exit. No state is persisted in the container itself. A fresh container is spun up for each session and does not attach to a running app container; a session can run without any app processes running.
  • Full app environment: The container has access to all add-ons (RDS, ElastiCache, S3, EFS, etc.) and environment variables configured for the app, exactly as a normal process would.
  • Interactive only: Console sessions are not suitable for unattended background work. Use tapit create task for jobs that should run to completion without user interaction.
  • Single session: Each tapit run invocation starts one container. There is no session sharing between users.

Resource Defaults

Console sessions inherit the default resource settings from your app configuration. You can override these per session:

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

Session Recording

Console session recording is available on Enterprise plans. Sessions are recorded in full and can be played back at any time from the Task Runs view in the web UI, providing a complete audit trail of interactive activity against your app.

Common Use Cases

  • Debugging: Inspect live application state, query databases directly, test library behaviour
  • Framework consoles: rails console, python manage.py shell, iex -S mix, etc.
  • Manual data fixes: Run one-off data corrections interactively, with full visibility of results before committing
  • System inspection: Check environment variables, connectivity to add-ons, or file system contents