Docs menu

Deploy and run

Buckets, queues and secrets

Store files in buckets, pass work between services with queues, keep secrets in step with your vault, rotate them, and ship logs elsewhere.

Explain it

Besides apps and databases, a project can store files in buckets, pass background work through queues, keep secrets in step with Doppler or Vault, rotate passwords on a schedule, and send logs to other tools.

How to do it: in a project, press Add for a bucket or a queue: CLI connects it to your app with variables, so there's nothing extra to install. Secret sync, rotation and log drains are in project settings.

"Add a bucket for user uploads and connect it to my web app."

Beyond apps and databases, CLI gives your project object storage for files, durable queues for background work, and tools that look after secrets for you. Each one connects to your app through variables, so there are no extra SDKs to install.

Buckets

A bucket stores files: user uploads, generated reports, images. Use a bucket rather than the container's disk, which is replaced on every deploy. Buckets are billed per GB stored each month.

Linking a bucket to a service gives it two variables: BUCKET_URL and BUCKET_TOKEN. Redeploy the service so it sees them.

In the dashboard: open the project's Settings and find Buckets.

From your terminal:

Terminal
cli bucket create uploads
cli buckets

The linked service gets the variables. Add --public to let anyone read files without a token.

Ask your agent:

"Add a bucket called uploads for web, so users can upload avatars."

With the API:

API
POST /v1/projects/:id/buckets
JSON
{ "name": "uploads", "link": { "serviceId": "svc_web123" } }

Use it from your app

Your app reads and writes files with plain HTTP requests, sending the token:

API
PUT $BUCKET_URL/avatars/42.png
GET $BUCKET_URL/avatars/42.png
DELETE $BUCKET_URL/avatars/42.png
GET $BUCKET_URL?prefix=avatars/
Authorization: Bearer $BUCKET_TOKEN

The body is the raw file, up to 100 MB. The last request lists files under a prefix.

To let a browser download or upload one file directly, make a link that expires. It can last from 1 minute to 7 days.

From your terminal:

Terminal
cli bucket put uploads ./report.pdf reports/october.pdf
cli bucket url uploads reports/october.pdf --days 2

With the API:

API
POST /v1/buckets/:id/sign
JSON
{ "key": "reports/october.pdf", "method": "GET", "seconds": 3600 }

method is GET to download or PUT to upload.

Queues

A queue holds messages for background work: one service sends jobs, another works through them. Messages are kept until a worker confirms it handled them. Queues are billed per operation.

Create a queue

Link the queue to every service that sends or receives. Each gets QUEUE_URL and QUEUE_TOKEN.

In the dashboard: open the project's Settings and find Queues.

From your terminal:

Terminal
cli queue create emails
cli queues

With the API:

API
POST /v1/projects/:id/queues
JSON
{ "name": "emails", "link": { "serviceIds": ["svc_web123", "svc_worker456"] }, "maxAttempts": 5, "visibilitySeconds": 30 }

Send messages

Producers post a JSON body, with Authorization: Bearer $QUEUE_TOKEN:

API
POST $QUEUE_URL/messages
JSON
{ "body": { "to": "[email protected]", "template": "welcome" } }

You can send up to 100 at once as {"messages": [...]}, and delay a message with delaySeconds.

Work through them

Workers ask for messages, handle them, then acknowledge them:

  1. POST $QUEUE_URL/receive with {"max": 10, "waitSeconds": 20}. With waitSeconds, the request waits up to 20 seconds for a message to arrive (long polling), instead of returning empty at once.
  2. Handle each message.
  3. POST $QUEUE_URL/ack with {"receipts": [...]} from the messages you handled.

A message you don't acknowledge comes back after the visibility window (30 seconds by default), so another worker can try it. To hand one back sooner, use POST $QUEUE_URL/nack.

Dead letters

After maxAttempts tries (5 by default), a message moves to the queue's dead letters instead of coming back. GET $QUEUE_URL/dead lists them, and POST $QUEUE_URL/redrive puts them back in the queue once you've fixed the cause.

Push mode

Instead of running a worker that polls, CLI can push each message to a path on your app:

Terminal
cli queue create emails --push /jobs/email
JSON
{ "name": "emails", "push": { "serviceId": "svc_worker456", "path": "/jobs/email" } }

Each push carries an X-CLI-Signature header, so your app can check it came from CLI.

Secret sync

Keep your variables in step with Doppler, HashiCorp Vault (KV v2), or any HTTPS endpoint that returns JSON. CLI pulls every 5 minutes and only changes the keys it wrote, so variables you set by hand are left alone. Syncs can fill one service's variables or the project's shared variables, and can redeploy when something changes. Setting one up needs an admin.

In the dashboard: open the project's Settings and find Secrets from your vault.

From your terminal:

Terminal
cli secrets sync doppler dp.st.prd.xxxx
cli secrets sync doppler dp.st.prd.xxxx --shared --redeploy
cli secrets

With the API:

API
POST /v1/projects/:id/secret-syncs
JSON
{ "provider": "vault", "token": "hvs.…", "url": "https://vault.example.com", "path": "secret/data/web", "serviceId": "svc_web123", "autoDeploy": true }

Use "serviceId": null for shared variables. Each sync raises a secrets_synced event.

Secret rotation

CLI can replace a secret on a schedule, such as a session signing key every 30 days. When it rotates, the old value stays available as KEY_PREVIOUS (for example SESSION_SECRET_PREVIOUS) for a grace period, 24 hours by default, so sessions and tokens signed with the old value still verify. Have your app accept both during that time.

On a database, rotation changes the password in place and redeploys the apps that use it. There's no key to name.

From your terminal:

Terminal
cli secrets rotate SESSION_SECRET --every 30
cli secrets rotate --service postgres --every 90

The second command rotates the postgres database's password.

With the API:

API
POST /v1/services/:id/rotations
POST /v1/rotations/:id/rotate
JSON
{ "key": "SESSION_SECRET", "everyDays": 30, "graceHours": 24 }

The second endpoint rotates now. Each rotation raises a secrets_rotated event.

Log drains

Send your services' output to Datadog, Axiom, Better Stack or any HTTPS endpoint. Secret values are masked before anything leaves CLI. A drain covers every running service in the project unless you pick some.

In the dashboard: open the project's Settings and find Log drains. Each drain has a button to send a test line.

With the API:

API
POST /v1/projects/:id/drains
POST /v1/projects/:id/drains/:drain/test
JSON
{ "target": { "kind": "datadog", "apiKey": "…" }, "services": ["svc_web123"] }

kind is datadog (with apiKey), axiom (with a token and dataset), betterstack (with a token) or http (with a URL).

Next steps