Workspace Configuration

Configurations in VibeControls let you store and manage named values — settings, preferences, and operational parameters — at different levels of your workspace hierarchy. Instead of hardcoding values in scripts or session commands, you define them once in a configuration and reference them wherever they are needed.

Navigate to VibeControls → Settings to access workspace-level configurations, or use the Settings tab within an agent, vibe, or session to manage configurations at those levels.

Configuration Scopes

Configurations are scoped to four levels of the hierarchy:

Scope	What It Controls
Workspace	Applies across your entire workspace — available to all agents, vibes, and sessions
Vibe	Applies to a specific vibe and all sessions that belong to it
Agent	Applies to a specific agent and all sessions running on it
Session	Applies only to a specific session

When the same key exists at multiple levels, the most specific scope wins. Session overrides agent, agent overrides vibe, vibe overrides workspace.

Because a session belongs to both a vibe and an agent, agent-scope values take precedence over vibe-scope values for that session. This is deliberate: the agent represents the machine context a session actually runs in, so values tied to the machine override values tied to the project.

Example. Suppose api_url is set to https://staging.example.com at the vibe level and https://prod.example.com at the agent level. A session in that vibe running on that agent will resolve api_url to https://prod.example.com — agent overrides vibe.

This cascade lets you set sensible defaults at the workspace level and override them for specific contexts without duplication.

Configuration Types

Each configuration entry has a type that describes what kind of value it holds:

Type	Description
String	A plain text value
Number	A numeric value
Boolean	true or false
Secret	An encrypted string — write-only for Viewers and Members after creation. Admins can reveal the stored value (see Permissions).
JSON	A structured JSON object or array
Multi-line	A text block, useful for scripts or certificate content

Choosing the right type ensures that values are validated correctly and displayed appropriately in the UI.

Managing Configuration Values

Adding a Configuration Entry

At the workspace level:

1. Navigate to Settings in the VibeControls sidebar
2. Click the Configurations tab
3. Click Add Configuration
4. Enter:

• Key — the name you will use to reference this value
• Value — the value to store
• Type — the value type
• Description (optional) — explain what this value is for

5. Click Save

At the vibe level:

1. Open the vibe detail page
2. Click the Configuration tab (or Environment for environment variables — configurations are distinct)
3. Click Add Configuration
4. Fill in key, value, type, and description
5. Click Save

At the agent level:

1. Open the agent detail page
2. Click the Settings tab
3. Find the Configurations section
4. Click Add Configuration and fill in the fields

At the session level:

1. Open the session detail page
2. Click Edit
3. Find the Configurations section
4. Add or override configuration values

Editing a Configuration Entry

1. Find the configuration entry in the relevant scope's list
2. Click the edit icon (pencil) next to it
3. Update the value or description
4. Click Save

Note: Secret-type values are write-only for non-Admin roles after saving — Viewers and Members cannot read them back, so to update them you overwrite with a new value. Admins retain the ability to reveal a stored secret (see Permissions).

Deleting a Configuration Entry

Click the delete icon (trash) next to a configuration entry and confirm the deletion. If a lower scope was overriding this entry, that override remains — deleting the parent does not cascade down.

Viewing Effective Configuration

On any agent, vibe, or session detail page, the Effective Configuration panel shows the final resolved values after applying the cascade from workspace → vibe → agent → session.

This view is useful for debugging — if a session is picking up an unexpected value, you can see exactly which scope it came from.

Use Cases

Feature Toggles

Store a boolean enable_experimental_ui at the workspace level, then override it to true for a specific vibe where you are testing the feature.

Environment-Specific Endpoints

Set an api_base_url at the workspace level pointing to your production API. Override it at the agent level for a machine that should talk to a staging API.

Shared Scripts Configuration

A script session that runs a deploy might need a deploy_bucket value. Store it in the vibe so any session in that vibe can use it, without repeating the value in every script.

Secrets Management

Store API keys, tokens, or passwords as Secret type configurations. They are encrypted at rest and never displayed in plain text after initial entry. Reference them in scripts or agent plugins without exposing them in session logs.

Configuration vs Environment Variables

VibeControls has both Configurations and Environment Variables (managed within vibes). They are similar but serve different purposes:

• Environment Variables are standard shell environment variables injected into session processes automatically (like .env files).
• Configurations are a structured store for any named values — they may or may not be used as environment variables. They are accessible to plugins, automations, and the CLI via the VibeControls API, not just as shell variables.

Use environment variables for values that need to be available as $VAR_NAME in shell sessions. Use configurations for values that need to be accessed programmatically, shared across multiple resource types, or stored with additional metadata.

Tips

• Always add a description to configuration entries. Future you (or a new team member) will thank you for knowing what JWT_SECRET_KEY is for.
• Use consistent key naming across your workspace — for example, always prefix vibe-scoped keys with the vibe name: myapp_database_url.
• Rotate secrets by simply overwriting them. The previous value is gone and cannot be recovered from the UI.