Getting started
Reference
Console Session

Console Session

Overview

A console session is an interactive terminal session that runs inside an ephemeral container. It is intended for live, hands-on work such as debugging, inspecting application state, or running framework consoles — not for one-off background tasks, which should use tapit create task instead.

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.), giving you a full application environment to work in.

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 Tapitale 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.

CLI Usage 

tapit [-a app_name] run 'bash' [local|memory|cpu|docker_tag|image|max_hours]=value

Launches an interactive console session. The CLI attaches to the running container so you interact with it in real time. When you exit the session the container is terminated and discarded.

Note: There is no tapit create console command. Use tapit run bash for interactive foreground sessions. For background tasks that run without a terminal window or session, use tapit create task instead.

Optional Parameters

  • -a app_name: Target a specific app. Defaults to the app configured in the current directory.
  • local: Run the session locally instead of in the cloud (useful for quick local debugging without spinning up a remote container).
  • memory: Memory allocation in GB. Defaults to the app’s configured value.
  • cpu: CPU allocation in vCPUs. Defaults to the app’s configured value.
  • docker_tag: Specific Docker image tag to use. Defaults to the latest deployed tag.
  • image: Custom container image for this session. Overrides the app’s own Docker image entirely. Any image can be used, including external or public images (e.g. ubuntu:24.04, public.ecr.aws/myorg/mytool:latest).
  • max_hours: Maximum session duration in hours before the container is automatically terminated. No limit by default.

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

Behaviour

  • Ephemeral: The container is created fresh for the session and destroyed when you exit. No state is persisted in the container itself.
  • 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

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
TasksVariables