Local Docker Deployment

Run Vibedata as a self-hosted Docker stack on your own machine using vibedata. After a handful of one-time commands, the CLI handles every remaining detail — rendering .env, pulling images, starting services, applying migrations, and importing laptop GitHub auth.

Setup path

The local Docker deployment of Vibedata uses the non-prod compose auth model: sign in to GitHub on the laptop before install, and sign in to Azure inside the container only when Fabric needs it. Generated compose/env files set NODE_ENV=development and AUTH_ENABLED=false; local delegated-auth/SSO mode is not a supported install compose output.

Path	When to use	What it adds
Development/non-prod compose	Single operator, local validation, demos	NODE_ENV=development, AUTH_ENABLED=false, no mandatory web-login gate
Production/cloud	Shared deployment with SSO and real owners	Use production bootstrap plus Org settings → Identity providers and Org settings → GitHub

What you'll need

• Docker Engine or Docker Desktop running on the host
• Access to a web browser on your laptop for the device-code prompts
• GitHub CLI (gh) on the host for the ambient GitHub session imported into the API container
• Azure CLI (az) only when Fabric workflows need the API container to hold an Azure session
• For production provider setup, cloud-admin authority in the provider portals: Entra/OIDC app registration rights and GitHub App registration/installation rights. Production SSO is configured through Vibedata bootstrap and Org Settings, not install compose.

How to install vibedata

Install the vibedata binary for your platform and put it on your PATH:

curl -fsSL https://github.com/accelerate-data/vibedata-official/releases/latest/download/install.sh | sh

The script downloads the binary for your OS/architecture from the latest release on accelerate-data/vibedata-official.

Verify the install:

vibedata version

How to install Vibedata

vibedata install compose

install compose installs the Vibedata version this CLI was built for — the CLI and Vibedata are paired strictly 1:1, so there is no version to choose. It reads everything it needs from DATA_DIR/state.json: host port choices, generated database secrets, the installation data-encryption key and explicit key identifier, and observability credentials. A fresh installation exposes Vibedata on port 5173; use --frontend-port <port> only when that port is unavailable. The selected port is persisted, so a later install without the flag keeps it. It does not prompt for anything on a fresh install, and it always renders development/non-prod auth (NODE_ENV=development, AUTH_ENABLED=false). Delegated auth and bootstrap-key configuration are production/cloud concerns, not supported compose installer inputs. Operators may manually edit generated files, but that is outside the supported installer contract.

LLM provider: Vibedata's LLM provider — the API key and optional base URL — is configured inside Vibedata after install, under Org settings → LLM.

Default install (lean / core-only)

The default install compose ships only the Vibedata core services — no LGTM or Alloy. The lean install needs roughly 3.5 GB of images plus ~1 GB of DATA_DIR headroom; adding --with-observability (LGTM/Grafana/Alloy) needs more than that — check vibedata doctor compose for the exact resource floor before installing.

Lean mode configures no OTLP endpoint, so the backend keeps a local log record: the pino files (server.log, error.log, http.log) under DATA_DIR/logs/, bounded by LOG_LOCAL_RETAIN_HOURS, with OpenTelemetry traces falling back to JSONL files in the same directory. The success message prints the resolved logs path. With --with-observability an endpoint is set, so no pino log file is written and docker logs api is the log record instead. The choice is persisted to state.json; pass --with-observability to opt in. Grafana credentials in state are preserved across the toggle so re-enabling never rotates them.

Opt-in observability

Flag	What it adds
--with-observability	LGTM (Grafana + Loki + Tempo + Prometheus) + Alloy, including LLM/agent trace visibility
--no-observability	Removes them, leaving the core services

--full-observability is retired — Vibedata no longer provisions Langfuse — and rejects with an actionable error instead of starting anything.

Requires Docker Desktop resources sized for the chosen profile.

Grafana access policy: Only a Vibedata Owner can open Grafana at /grafana/ or call its API there. Vibedata checks the caller on every request, so removing the Vibedata Owner role takes effect on the next click. A Vibedata Owner enters with their Vibedata identity; Grafana creates their account on first use with the Editor role. Editor can open and edit dashboards and use Explore, but cannot add, change or delete data sources. Other signed-in users get 403 from /grafana/, but they can still use Vibedata's own observability API, which shows them only their own Domains and Intents. A browser without a Vibedata session goes to Vibedata login; an API call without credentials gets 401.

Grafana has no host port. It runs on its own internal Docker network, vd-grafana, which only the frontend, the backend and Alloy join; agent and Obot containers cannot reach it. Grafana's login form is turned off. The admin account and GF_SECURITY_ADMIN_PASSWORD stay for emergency use from the Docker host only, for example docker exec into the otel-lgtm container and curl -u admin:<password> http://localhost:3000/api/user.

Forgetting the flag on a later run never turns observability off. compose up with no flag starts whatever is installed, and re-running install compose without one stops and shows you both commands — the one that keeps your current profile and the one that removes it. Removal is always --no-observability, and even then the collected data stays under DATA_DIR, so re-enabling picks up where you left off.

Per-container memory caps

Every container carries a memory cap, so an operator can size the host for the chosen profile. If a container exceeds its cap the kernel stops it (exit code 137) and Compose restarts it — the stack can look healthy again while the symptom shows up elsewhere, usually as a page or request that never finishes. docker inspect --format '{{.State.OOMKilled}} {{.RestartCount}}' <container> tells you whether that happened.

Core services:

Profile (flag)	Container	Memory cap
all	api	1 GB
all	postgres	512 MB
all	obot	512 MB
all	frontend	64 MB

Optional observability containers:

Profile (flag)	Container	Memory cap
--with-observability (LGTM)	otel-lgtm	2 GB
--with-observability (LGTM)	alloy	512 MB
--with-observability (LGTM)	nginx	64 MB
--with-observability (LGTM)	nginx-exporter	32 MB
--with-observability (LGTM)	cadvisor	256 MB

--full-observability is retired — Vibedata no longer provisions Langfuse — and rejects with an actionable error instead of rendering anything.

cadvisor (256 MB, shown above) runs with privileged: true so it can read every other container's cgroups — that means the observability profile mounts the host root and the Docker socket into a privileged container, and the metrics it scrapes stay on the internal network (no host port is published). It is opt-in via --with-observability and is not present in a core install.

Core caps total ≈ 2.1 GB, and each activated Intent adds an agent container beyond that. LGTM adds ≈ 2.8 GB of capped headroom on top of core. Core installs have no memory admission gate — the observability profile does. These caps live in deploy/docker/docker-compose.yml and docker-compose.lgtm.yml — treat those files as the source of truth if the numbers here drift.

After resolving inputs, install compose:

1. Validates Docker authority, host ports, and a writable DATA_DIR
2. Renders DATA_DIR/.env and DATA_DIR/docker-compose.yml
3. Pulls the selected Vibedata images, upstream PostgreSQL, and (in full mode) observability images
4. Starts the Compose stack
5. Applies database migrations
6. Reports ready, degraded, or blocked

DATA_DIR defaults to ~/.vibedata/studio on macOS and Linux, %USERPROFILE%\.vibedata\studio on Windows. Override by exporting DATA_DIR before running the command.

Generated secret files

DATA_DIR/.env and DATA_DIR/state.json contain generated service, signing, encryption, and, when bundled companion apps are configured, OAuth-client values. On POSIX hosts, Vibedata writes both files as owner-readable only (0600) and preserves that restriction on rerender and update. Do not share these files with a group or commit or copy them into a shared location.

Docker's UID mapping can determine the owning account on the host. If a manual copy, restore, or filesystem migration broadens access, restore owner-only access before restarting or updating the stack:

chmod 600 "$DATA_DIR/.env" "$DATA_DIR/state.json"

credentials.json is also owner-only, but stores CLI metadata only; login tokens remain in the operating-system keyring. The gh-config, azure-config and aws-config directories are credential caches managed by the GitHub, Azure and AWS CLIs respectively, so keep the entire DATA_DIR private.

Accessing Vibedata from a different machine

Vibedata's UI binds all host interfaces (0.0.0.0), so from another machine on the same network just open http://<host-ip>:5173 — no SSH tunnel needed. Vibedata itself accepts whatever address you open it with, so a hostname works too.

To use any bundled companion app over the network, set --studio-url. Vibedata's own screens work off-host with no flag, but the companion apps — Obot (always installed) and, with observability, Grafana — sign in through Vibedata's OAuth, and that login must bounce back to a fixed pre-registered address. Install with --studio-url set to the address others will use:

vibedata install compose --studio-url http://<host-ip>:5173
# with observability:
vibedata install compose --with-observability --studio-url http://<host-ip>:5173

This one value drives Vibedata and every companion app. It's persisted, so compose up, restart, and update keep it. To change it later, reinstall with the new --studio-url — the companion OAuth clients are re-registered to the new address automatically. It must be http://host or http://host:port only (no path, and HTTPS is not supported for Local Docker).

Security: Local Docker runs with no login, so anyone who can reach the host on port 5173 gets full access. Use your host firewall or network to control who can reach it. Only the Vibedata UI port is exposed this way; databases and other internal services stay private.

Because there is no login, Vibedata acts with the GitHub, Azure and AWS sessions you signed in for it (see How to sign in to Azure and GitHub). Anyone who can reach the port can use them. Do not expose it beyond your own machine.

If the host isn't directly reachable (e.g. a cloud VM behind a firewall), forward the port over SSH instead and open http://localhost:5173:

ssh -N -L 5173:localhost:5173 <user>@<remote-host>

How to sign in to Azure and GitHub

Before install, sign in to GitHub on your laptop with the account you want Vibedata to use for local ambient login and repo operations:

gh auth login --scopes repo,read:org,workflow

During vibedata install compose, vibedata imports that laptop GitHub session into the Vibedata API container and stores it under DATA_DIR/gh-config. If GitHub is not signed in on the laptop, install blocks and asks you to run gh auth login, then rerun install.

Once the stack is up, sign Vibedata's container into Azure if you use Fabric. This command runs inside the Vibedata container, and the device-code prompt streams to your terminal.

The commands below assume the default DATA_DIR of ~/.vibedata/studio. If you installed with a custom DATA_DIR, substitute that path for ~/.vibedata/studio.

# Sign in to Azure (device-code flow; pick a subscription at the prompt
# when you have several)
docker compose -f ~/.vibedata/studio/docker-compose.yml exec -it api az login --use-device-code

# Verify GitHub in the API container
docker compose -f ~/.vibedata/studio/docker-compose.yml exec api gh auth token >/dev/null

# Verify Azure in the API container when Fabric needs it
docker compose -f ~/.vibedata/studio/docker-compose.yml exec api az account show --output table

Skip az login if you only use DuckDB-target pipelines (no Fabric). Laptop gh auth login is required to create a domain.

Local GitHub CLI identity

Local Docker uses the operator's laptop GitHub CLI session as Vibedata's user identity. vibedata install compose imports the laptop token into the API container; you do not need to mount ~/.config/gh or run gh auth login inside the container.

Verify the imported session from inside the running API container:

docker compose -f ~/.vibedata/studio/docker-compose.yml exec api gh auth token >/dev/null

If that command fails, run gh auth login --scopes repo,read:org,workflow on the laptop and rerun vibedata install compose. Vibedata ignores GIT_PAT_TOKEN and GITHUB_PAT for ambient GitHub auth; the gh CLI session is the source of truth.

Upgrade note — GitHub workflow permission

The GitHub session needs the workflow scope when Vibedata pushes a Domain template that creates or changes a file in .github/workflows/. A deployment can keep working until that first changed workflow file is pushed, so a successful earlier Intent does not prove the scope is present.

Before or after updating Vibedata, check the API container's GitHub session:

docker compose -f ~/.vibedata/studio/docker-compose.yml exec api gh auth status -h github.com

If the output does not list workflow, refresh the persisted container session:

docker compose -f ~/.vibedata/studio/docker-compose.yml exec -it api gh auth refresh -h github.com -s workflow

The command updates DATA_DIR/gh-config; no Vibedata or Docker restart is needed. For a different laptop GitHub account, rerun vibedata install compose instead.

To switch the active Azure subscription later without signing in again, list available subscriptions and set by ID or display name (a bare number is not valid):

# List subscriptions to find the ID or name you want
docker compose -f ~/.vibedata/studio/docker-compose.yml exec -T api az account list --output table

# Set by subscription ID (preferred — UUID, no ambiguity)
docker compose -f ~/.vibedata/studio/docker-compose.yml exec -T api az account set --subscription 8b3a7f9d-4e2c-4af1-9234-1234abcd5678

# Or set by display name (quote it if it has spaces)
docker compose -f ~/.vibedata/studio/docker-compose.yml exec -T api az account set --subscription "My Subscription"

These commands cover the provider tokens Vibedata's backend needs, separate from Vibedata's web-login gate (AUTH_ENABLED).

Persistence across container restart

Sessions live in bind-mounted folders under DATA_DIR (azure-config/, gh-config/ and aws-config/), so docker compose down && up keeps you signed in. You only sign in again when:

• You explicitly re-run az login or aws sso login in the container, or gh auth login on the laptop.
• The refresh token expires. The three differ sharply: Azure refresh tokens are ~90 days sliding, GitHub tokens typically last until you revoke them, and an AWS IAM Identity Center session defaults to 8 hours (an administrator can set 15 minutes to 90 days). Expect to re-run aws sso login far more often than the other two, and note that Vibedata's auth status does not report AWS readiness — an expired session surfaces as a failing Redshift operation rather than a sign-in prompt.
• You delete DATA_DIR or its cache folders.

How to update Vibedata

vibedata update compose

Reuses every value already in DATA_DIR/state.json — zero prompts. Pulls new images, recreates containers, reapplies migrations, and reconnects to your existing PostgreSQL and observability data. If anything fails, the command reports a blocked state and leaves the existing installation intact.

update compose preserves the persisted observability profile — if the install was lean, the update stays lean. To change topology, re-run install compose or compose up with the desired --with-observability flag (or no flag to return to lean).

update compose takes a backup for you before it replaces any container — see How to back up and restore.

It also stops with a blocked state if DATA_DIR/state.json has no data-encryption-key or no explicit data-encryption-key-id, rather than generating or defaulting either value. A changed keyring would leave every credential Vibedata has already encrypted permanently unreadable. Restore the original state.json from a backup, or restore a whole package with vibedata restore compose; an existing installation cannot be repaired by choosing a replacement key.

To change Vibedata's LLM provider, use Org settings → LLM inside Vibedata.

What your users see during an update

update compose shows every Vibedata page a Vibedata is under maintenance notice for the whole window, and clears it once Vibedata answers its readiness check. You do not switch it on or off yourself.

It stays on if the update fails part-way. That is deliberate: a half-replaced Vibedata should not take traffic. Fix the cause, run the update again, and it clears itself when the run succeeds.

If you need to serve normally again before then — say you restored a backup instead — clear it yourself:

vibedata maintenance off

You can also take Vibedata offline deliberately, for a database migration or any other work:

vibedata maintenance on

A window you open this way is yours to close. An update running inside it will not clear it for you.

The notice is served by the frontend container itself, so it keeps working while the API and database are down, and switching it needs no restart.

How to back up and restore

Database migrations have no down-path, so an update that goes wrong is recovered by restoring a backup, not by rolling the images back. A backup is therefore taken automatically before every update, and you can take one whenever you like.

Automatic, before every update

vibedata update compose backs up on its own: it holds the lifecycle lock, waits for the upgrade gate to clear, then packages the running install just before containers are replaced. If the backup fails, the update stops and the existing installation is left untouched. --skip-backup overrides that and says clearly in the output that the update has no restore point — a failure then has no way back.

Manual, any time

vibedata backup compose

Packages the running install into DATA_DIR/backups/manual-<version>-<timestamp>/ and prints the path. Backups taken by an update are named pre-upgrade-<target version>/ instead. The newest 2 packages are kept; older ones and any half-written folder are removed.

One package contains a dump per database (Vibedata, the agent service, and Langfuse when it is installed), a tar of the container /data paths that exist nowhere else — including the vd-openhands-nfs subpaths (/data/secrets, /data/duckdb, /data/openhands, /data/uploads, /data/cache, /data/plugins, /data/.openhands) — a copy of .env and state.json, and a manifest.json written last. That last file is what marks the package complete — a folder without one is never restored from.

The backups folder is on the same disk as the data it protects. One machine has no second disk to offer, so a lost disk loses both. If this installation matters, copy the package folders somewhere else. They are as sensitive as the rest of DATA_DIR: they hold the encryption key and plaintext connector secrets, so keep them private.

Restore

vibedata restore compose --from pre-upgrade-v1.2.3

--from takes a folder name under DATA_DIR/backups/ or an absolute path to a package anywhere. The command prints the package's Vibedata version and date and asks for confirmation first; --yes skips the prompt for scripted runs. It then stops the stack, puts the package's .env and state.json back, restores the databases and data files, and starts the stack again on the package's own images — so a failed update lands you back on the version the package came from.

Langfuse's data is restored only when its local trace store is still in place. Without those traces its dashboards would point at nothing, so a package restored onto a wiped machine starts Langfuse empty.

After a restore, sign in again where Vibedata needs a platform session (gh on the laptop, and az inside the container if you use Fabric). Those token caches are deliberately not part of a package.

Moving an installation to another machine

Because .env and state.json ride inside the package, there is no key to move by hand. On the new machine, install Vibedata with the vibedata binary matching the package's Vibedata version, copy the package folder across, then restore it:

vibedata install compose
vibedata restore compose --from /path/to/pre-upgrade-v1.2.3

How to control the running stack

Command	What it does
vibedata compose up [--with-observability]	Starts the stack from DATA_DIR. Bare invocation re-renders against the lean profile; pass --with-observability to opt in. Persists the choice.
vibedata compose down	Stops services; preserves databases, app data, generated secrets, plugin storage, and observability state
vibedata compose restart	Restarts services and re-runs readiness checks
vibedata cleanup [--force | -y] [--keep-images]	Tears the stack down and reclaims Docker resources — removes this project's containers, network, and (by default) images. Preserves DATA_DIR and the named postgres and vd-openhands-nfs volumes, which hold the databases, secrets, and other generated state. Scoped to the Vibedata Compose project only. Prints a summary and prompts for confirmation unless --force/-y; --keep-images keeps pulled images. Idempotent on an already-clean environment.

compose up/down/restart operate on the already-rendered docker-compose.yml in DATA_DIR and never modify state or prompt for input. cleanup is the exception: it removes Docker resources and prompts for confirmation first (skip with --force).

Production SSO and GitHub setup

Production/cloud deployments use AUTH_ENABLED=true and a bootstrap key, but that is not a local Docker installer mode. A cloud admin registers Entra/OIDC apps in the provider portal, then uses production Vibedata bootstrap to enter Org settings → Identity providers. The bootstrap key gets the operator into Org Settings only for SSO setup and the first-owner grant; it is not the steady-state admin identity.

After the Identity Provider test succeeds in production Vibedata, the operator grants a real user vibedata_owner with the Users API/UI, signs in normally through SSO as that owner, then configures Org settings → GitHub, Org settings → Data Platforms, users, and other admin surfaces; machine credentials are issued through the published Service Principal API. The GitHub App is created in GitHub developer settings, installed on the target org/repositories, and registered in Org settings → GitHub after owner sign-in.

Global options

These work on every vibedata command:

Option	Effect
--json	Emits machine-readable output. Long-running commands emit event streams.
--verbose	Extended diagnostic output. Raw secrets are still redacted.

What you'll see (states)

• Ready — installation complete, app entrypoint reachable, migrations applied, durable storage writable
• Degraded — install or update succeeded, but a non-critical surface (such as observability or one provider's sign-in) is reporting an issue; the command names the affected check and the operator action
• Blocked — the command cannot proceed safely; reasons include missing Docker authority, port conflicts, registry failure, missing provider authority, missing CLI sign-in, stale generated files, or unrecoverable encryption material. The output names the precondition that failed and the operator action required.
• Not configured — DATA_DIR is missing, unreadable, or not a vibedata-managed installation

Quick reference

Default (no SSO)

Command	What it does
vibedata install compose	First-time install or recovery from durable state (installs the Vibedata version this CLI was built for, lean profile by default).
vibedata install compose --frontend-port <port>	Use another browser-facing host port when 5173 is unavailable. It persists for later lifecycle commands until explicitly changed.
vibedata install compose --with-observability	Install with LGTM + Alloy
vibedata install compose --studio-url http://<host-ip>:5173	Set the external URL others use to reach Vibedata over the LAN; drives Vibedata and companion-app (Obot always, Grafana with observability) logins. http://host[:port] only.
docker compose -f ~/.vibedata/studio/docker-compose.yml exec -it api az login --use-device-code	Sign Vibedata's container into Azure (device-code flow)
docker compose ... exec -it api az account set --subscription <subscription-id>	Switch the active Azure subscription without re-signing in
gh auth login --scopes repo,read:org,workflow	Sign the laptop into GitHub; vibedata install compose imports this session into Vibedata's container
vibedata compose up [--with-observability] / down / restart	Start (lean by default, or opt into the observability stack), stop (preserving data), or restart
vibedata update compose	Roll the install to the Vibedata version this CLI was built for; preserves data and backs up first
vibedata backup compose	Package the running install into DATA_DIR/backups/; keeps the newest 2 packages
vibedata restore compose --from <folder | path> [--yes]	Put a package back in place, on the version it came from. Confirms first unless --yes
vibedata cleanup [--force | -y] [--keep-images]	Tear the stack down and reclaim Docker resources (containers, network, images); preserves DATA_DIR and the named postgres and vd-openhands-nfs volumes. Prompts unless --force; --keep-images keeps images
vibedata version	Print the CLI version

Exit codes: 0 success · 1 generic error · 2 misuse · 3 blocked · 4 not configured.

Single-user evaluation settings

Local Docker has two single-user evaluation modes:

Mode	Use it when	Observability
Base	You need the smallest Vibedata evaluation install.	No Grafana or Alloy services are rendered.
--with-observability	You want evaluation diagnostics, including agent and LLM trace visibility.	Grafana, Loki, Tempo, Prometheus, and Alloy collect Vibedata telemetry.

--full-observability is retired — Vibedata no longer provisions Langfuse — and rejects with an actionable error instead of rendering anything.

Observability retention and query limits

With --with-observability, you can set how long the stack keeps logs, traces and metrics, and the native query limits of Grafana, Loki, Tempo and Prometheus. Pass each setting as a flag to vibedata install compose or vibedata compose up:

vibedata compose up --observability-setting LOKI_RETENTION_HOURS=72

• Repeat the flag to set more than one value.
• Leave the value empty to return a setting to its default: --observability-setting LOKI_RETENTION_HOURS=.
• The installer checks every value before Docker starts. It rejects an unknown setting, a value out of range, or a TEMPO_SEARCH_MAX_DURATION shorter than TEMPO_RETENTION_HOURS, and it tells you the allowed values.
• The installer saves the values in DATA_DIR/state.json. Every later compose up, install compose, and update compose keeps them. You do not need to set them again.
• The change restarts the observability stack.
• The flag needs the observability stack. Without --with-observability, the command stops before it saves anything.

A duration uses s, m or h, such as 30s, 5m or 2h.

Setting	Unit	Default	Allowed	What it controls
LOKI_RETENTION_HOURS	hours	168	1–168	How long Loki keeps logs.
TEMPO_RETENTION_HOURS	hours	168	1–168	How long Tempo keeps traces.
METRICS_RETENTION_HOURS	hours	168	1–168	How long Prometheus keeps metrics.
GF_DATAPROXY_TIMEOUT	seconds	30	1–3600	How long Grafana waits for a datasource.
GRAFANA_LOKI_MAX_LINES	lines	1000	1–100000	Log lines Grafana Explore asks for. Grafana Explore only; the Loki API default stays 100.
LOKI_MAX_ENTRIES_LIMIT_PER_QUERY	entries	5000	1–1000000	The most log entries one Loki query can return.
LOKI_QUERY_TIMEOUT	duration	1m	1s–1h	How long one Loki query can run.
TEMPO_SEARCH_DEFAULT_RESULT_LIMIT	traces	20	1–1000000	Traces a Tempo search returns when it names no limit.
TEMPO_SEARCH_MAX_RESULT_LIMIT	traces	0	0–1000000	The most traces one Tempo search can ask for. 0 means no ceiling.
TEMPO_SEARCH_MAX_DURATION	duration	168h	1h–8760h	The longest time range one Tempo search can cover. Must be at least TEMPO_RETENTION_HOURS.
TEMPO_MAX_SPANS_PER_SPAN_SET	spans	100	0–10000	The most spans per span set a Tempo search can ask for. 0 means no ceiling.
TEMPO_SEARCH_QUERY_TIMEOUT	duration	30s	1s–1h	How long one Tempo search can run.
TEMPO_TRACE_BY_ID_QUERY_TIMEOUT	duration	10s	1s–1h	How long one Tempo trace lookup can run.
PROMETHEUS_QUERY_TIMEOUT	duration	2m	1s–1h	How long one Prometheus query can run.
PROMETHEUS_QUERY_MAX_SAMPLES	samples	50000000	1–1000000000	The most samples one Prometheus query can load into memory.

Vibedata shows the values in use, read-only, under Org settings → Capacity.

Before this flag existed, retention was set by editing DATA_DIR/.env. An install that still has those edits keeps them: the first render after you update adopts LOKI_RETENTION_HOURS, TEMPO_RETENTION_HOURS and METRICS_RETENTION_HOURS from .env into state.json, once. After that, use the flag. A later hand edit of these settings in .env is written over on the next render. If an adopted value is outside 1–168 hours (for example, the old 336-hour metrics default), the command rejects it before Docker starts. Set a valid value with the flag, or reset it with KEY=.

Other supported settings

Regardless of observability mode, the generated DATA_DIR/.env supports LOG_LEVEL (default info; one of trace, debug, info, warn, error, fatal, silent), OPENHANDS_LOG_LEVEL (default INFO; one of DEBUG, INFO, WARNING, ERROR, CRITICAL), and LOG_LOCAL_RETAIN_HOURS (default 168; 1-168 hours inclusive, the same ceiling as the retention settings above). To change one, edit DATA_DIR/.env, then run vibedata compose up --use-rendered-config. That command starts the already-selected topology from the edited file without re-rendering it.

LOG_LOCAL_RETAIN_HOURS bounds the pino server/error/http logs, and the startup sweep also matches trace files: on restart it removes any traces-*.jsonl older than this value, so a value below 24 hours shortens trace retention. When Vibedata runs without an OTLP endpoint, the file-mode trace exporter additionally bounds traces on its own runtime budget of roughly 24 hours / about 1.1 GB, which is not derived from this value.

A normal compose up, install, or update re-renders .env and restores the defaults of these .env settings. The observability settings above are not affected, because the installer keeps them in state.json. Changing arbitrary generated environment variables is unsupported: internal URLs, network names, images, secrets, and raw OpenTelemetry settings can break the deployment. The complete defaults, restart scope, and boundaries are in docs/design/container-architecture/README.md under "Single-user local Docker tuning contract."

These modes do not size Vibedata for multiple concurrent agent turns. Kubernetes capacity settings for that workload are being defined separately in VD-3518.

Related

• Functional spec: docs/functional/vibedata-cli/README.md
• Functional spec: docs/functional/container-deployment/README.md
• Architecture: docs/design/container-architecture/README.md