Skip to main content
troqcloud Addons are fully managed infrastructure services that run alongside your applications on the troqcloud fleet. When you attach an addon to an app, the platform provisions a dedicated container on the same fleet node as your application, wires network isolation, mounts a persistent volume for data durability, injects the connection secret into your app’s environment, and sends the credentials to your registered email address. You own and control the full lifecycle, from provisioning and suspension to resume and deletion, entirely from the CLI. The following addon types are available on the platform: Every addon carries its own persistent volume. Suspension stops the container but leaves the volume intact. Deletion permanently removes both. There is no shared infrastructure, and each addon is isolated to the workspace that provisioned it.

Security Model

Connection strings and credentials are never displayed in the CLI output. When you provision an addon, the platform injects the connection secret directly into your application’s environment as a secret, then sends the full credentials to your email address. This keeps sensitive database URLs, passwords, and access keys out of terminal history, logs, and CI/CD output entirely. If you need to retrieve credentials, check your email. If you need to rotate them, re-run troq addons apply for the same addon type.

Context and Directory Convention

Like all troq commands, the addon commands resolve the target application from the troq.toml file in your current working directory. There is no session-level “active app” stored anywhere. Every command reads the file at runtime. This means:
If you are outside an app directory or there is no troq.toml, the CLI will present an interactive fuzzy selector to pick the app. In scripts or CI pipelines, pass --app-id explicitly.

Viewing the Addon Catalog

troq addons catalog lists every addon type available in your workspace. This is the canonical way to see what the platform can provision before running apply.
The catalog returns each supported type and its runtime backend. Availability is determined by your workspace tier. If a type is listed, it can be provisioned immediately.

Listing Addons for an App

troq addons list returns all addons currently attached to an application, their types, runtime status, and whether they are ready to accept connections.
The runtime_ready field indicates whether the addon container is running and healthy. The runtime_state field shows the current container state: running, stopped, or error. Addons with status: active and runtime_ready: true are fully operational.

Inspecting an Addon

troq addons show returns the full record for a single addon. When run interactively, the CLI fetches the list of addons and presents a fuzzy selector:
In non-interactive mode or scripts, pass --addon-id directly:
The record includes the addon type, code, attached app, workspace, lifecycle status, runtime state, and timestamps. Connection strings are not included in the output, they were delivered to your email when the addon was provisioned.

Provisioning an Addon

troq addons apply is the primary command for attaching a managed service to your application. It provisions the runtime container, mounts the persistent volume, registers the connection secret into your app’s secret store, and sends the full credentials to your email.
When run without --addon-type, the CLI presents an interactive selector showing available types from the catalog. Each entry indicates whether you already have an addon of that type attached. What happens during provisioning:
  1. The CLI resolves the app from troq.toml or the --app-id flag.
  2. The platform creates the addon record in the database and assigns a unique addon code (e.g. ADD-00000030).
  3. A provisioning job is dispatched to the fleet node hosting your application via the deployer.
  4. On the node, the platform pulls the addon container image if not already cached, creates a dedicated data volume, configures network isolation, and starts the container.
  5. Once the container is healthy, the platform writes the connection secret into your app’s secret store under the default key for that addon type (DATABASE_URL, MYSQL_URL, MONGODB_URL, REDIS_URL, MINIO_URL).
  6. The full credentials, including the connection string, host, port, and any admin credentials, are sent to your registered email address.
  7. The CLI prints a summary and instructs you to run troq ship so your application picks up the new secret.
After provisioning, your app does not automatically reload. Run troq ship to trigger a new deployment that picks up the injected secret. The addon is live and accepting connections before the ship completes, but troq ship is required to expose the new secret to your running application process.

Applying Multiple Addons

You can apply multiple addon types in a single invocation:
Each addon is provisioned sequentially. If one fails, the others already provisioned are not rolled back, you can re-run apply for the failing type safely.

Custom Secret Keys

By default, the connection secret is stored under the standard environment variable name for each addon type. To store it under a custom key:

Persisting to troq.toml

By default, apply writes the provisioned addon types to troq.toml under an addons key. This allows subsequent apply runs (e.g. in CI) to reproduce the same set of addons without flags. To disable this:

What Happens if the Addon Already Exists

If an addon of the requested type is already attached to the app, the CLI informs you and prompts whether you want to provision an additional one. In non-interactive environments, the duplicate is skipped automatically. Use a separate --secret-key if you need two databases of the same type with distinct environment variable names.

Suspending an Addon

troq addons suspend stops the addon container on the fleet node without removing the data volume. The addon record remains in the database with status suspended. All data on the persistent volume is preserved.
When run without --addon-id, the CLI presents a fuzzy selector listing all active addons for the workspace. Suspension is appropriate when you need to take a database offline temporarily, for maintenance, cost reduction, or before a planned deletion. Your application will lose connectivity to the addon as soon as suspension completes. Make sure your application handles connection errors gracefully before suspending an addon that is actively in use. What happens on suspend:
  1. The platform transitions the addon status from active to suspended.
  2. A control event is dispatched to the fleet node via the deployer.
  3. The node agent stops the addon container via SIGTERM.
  4. The container exits. The data volume remains mounted and intact.

Resuming an Addon

troq addons resume restarts a suspended addon from its last known state. The data volume is remounted and the container is started from the same image. No re-provisioning is required.
The addon transitions from suspended back to active. Your application will regain connectivity automatically once the container is healthy, no secret rotation or troq ship is required unless your app caches the connection at startup.

Deleting an Addon

troq addons delete permanently removes an addon from the platform. The container is stopped, the persistent volume is deleted, and all data stored in it is gone. This is not reversible.
The CLI presents a confirmation prompt before proceeding:
Export your data before deleting. Connect to the database using the credentials from your email, run a dump or export, and verify the backup before confirming deletion. Once confirmed, the data cannot be recovered. What happens on delete:
  1. The platform stops the addon container on the fleet node.
  2. The Docker volume holding the addon data is removed from the node filesystem.
  3. The addon record is marked as deleted in the database.
  4. The connection secret injected into your app’s secret store is revoked.
After deletion, troq addons list will no longer show the addon. If your application is still running with the now-invalid secret, it will begin receiving connection errors. Run troq ship after deletion to redeploy without the stale secret.

Non-Interactive and Automation Usage

All troq addons commands work without prompts when the required identifiers are supplied as flags. This is the expected pattern in CI/CD pipelines and deployment scripts.
Pass --yes before addons to suppress confirmation prompts in destructive operations. Without --yes, deletion will block waiting for terminal input.

Output Formats

All addons commands support --output table, --output json, and --output jsonl. Table is the default and is formatted for human reading. JSON and JSONL carry the full response payload and are suitable for scripting and downstream tooling.
Note that connection strings are excluded from all output formats regardless of the mode selected. Credentials are only delivered via email.

Permission Requirements

Read operations (list, show, catalog) require addons.read. Write and lifecycle operations (apply, suspend, resume, delete) require addons.write. You can verify your access with:
If access is missing, ask your workspace owner to assign a role that carries the required permission. Use troq rbac roles-permissions-list to see what each role grants before requesting a change. Last Updated: 2026-05-11