vibecontrols-sdk 2026.523.1

Official Python SDK for VibeControls — thin shell over burdenoff-sdk-libs

vibecontrols-sdk

Official Python SDK for VibeControls -- development environment management for the Burdenoff platform.

Features

• Async/await support built on httpx
• Dual-endpoint GraphQL client (workspace + global gateways)
• 14 domain modules covering the full VibeControls API
• Multiple auth flows: email/password, device code, PKCE, client credentials
• Automatic token refresh with configurable callback
• Retry with exponential backoff
• Typed error hierarchy
• Full type hints with py.typed marker

Installation

pip install vibecontrols-sdk

# Development install
pip install -e ".[dev]"

Quick Start

import asyncio
from vibecontrols_sdk import VibeControlsSDK, VibeControlsConfig

async def main():
    sdk = VibeControlsSDK(VibeControlsConfig(
        workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
        global_endpoint="https://graphql.burdenoff.com/global/graphql",
    ))

    # Sign in with email/password
    auth = await sdk.auth.sign_in("[e-mail]", "password")
    print(f"Signed in as {auth['user']['fullName']}")

    # List vibes
    vibes = await sdk.vibes.list()

    # List sessions
    sessions = await sdk.sessions.list()

    await sdk.close()

asyncio.run(main())

Configuration

from vibecontrols_sdk import VibeControlsConfig

config = VibeControlsConfig(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",

    # OAuth2 (optional, for device code / PKCE / client credentials flows)
    oidc_issuer="https://auth.burdenoff.com",
    client_id="vibecontrols-cli",
    client_secret=None,           # Only for client credentials flow
    redirect_uri=None,            # Only for PKCE flow

    # Pre-existing tokens (optional)
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,

    timeout=30.0,                 # Request timeout in seconds
    auto_refresh=True,            # Auto-refresh tokens before expiry
    on_token_refresh=None,        # Callback for external token persistence
)

Modules

All methods are async. Access each module as a property on the VibeControlsSDK instance.

Module	Property	Description
Auth	sdk.auth	Sign in/up, sign out, token refresh, device code, PKCE, client credentials
Agents	sdk.agents	Agent CRUD, heartbeat, probes, plugin management
Vibes	sdk.vibes	Vibe (project/workspace) CRUD and management
Sessions	sdk.sessions	Terminal session management
Notes	sdk.notes	Note CRUD operations
Configuration	sdk.configuration	Key-value configuration management
Webhooks	sdk.webhooks	Webhook CRUD and management
Docs	sdk.docs	Documentation site management
VibeDeck	sdk.vibedeck	VibeDeck management (decks and buttons)
Targets	sdk.targets	Target machine management
Audit	sdk.audit	Audit log queries
UI Session	sdk.ui_session	UI session state management
Tunnels	sdk.tunnels	Agent tunnel management
AI Tool Events	sdk.ai_tool_events	AI tool event tracking

Authentication Flows

Email / Password

auth = await sdk.auth.sign_in("[e-mail]", "password")

Device Code (CLI / headless)

device = await sdk.auth.start_device_code_flow()
print(f"Visit {device['verification_uri_complete']} and enter code {device['user_code']}")
# SDK polls automatically until the user authorizes

PKCE (browser-based)

challenge = sdk.auth.build_authorization_url()
# Redirect user to challenge["url"]
# After callback:
result = await sdk.auth.exchange_auth_code(code, challenge["codeVerifier"])

Client Credentials (machine-to-machine)

config = VibeControlsConfig(
    ...,
    client_id="my-service",
    client_secret="secret",
)
sdk = VibeControlsSDK(config)
# Tokens are obtained automatically on first request

Error Handling

from vibecontrols_sdk.errors import (
    VibeControlsError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in("[e-mail]", "wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except VibeControlsError as e:
    print(f"SDK error: {e}")

Examples

See the examples/ directory:

• basic_usage.py -- Sign in, list vibes and sessions
• advanced_usage.py -- Device code flow, PKCE flow, token management

Development

# Create virtual environment
python -m venv venv && source venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Format
black src/ tests/ examples/
isort src/ tests/ examples/

# Lint
flake8 src/ tests/ examples/
mypy src/

# Test
pytest
pytest --cov=vibecontrols_sdk --cov-report=html

Project Structure

vibecontrols-sdk-python/
  src/vibecontrols_sdk/
    __init__.py          # VibeControlsSDK facade
    client/              # Dual-endpoint GraphQL client
    auth/                # Auth module + PKCE utilities
    agent/               # Agent management
    vibe/                # Vibe management
    session/             # Session management
    note/                # Note management
    configuration/       # Key-value config
    webhook/             # Webhooks
    docs/                # Documentation sites
    vibedeck/            # VibeDeck (decks + buttons)
    target/              # Target machines
    audit/               # Audit logs
    ui_session/          # UI session state
    tunnel/              # Tunnels
    ai_tool_event/       # AI tool events
    types/               # Type definitions
    errors.py            # Error hierarchy
  tests/
  examples/
  docs/
  pyproject.toml

License

Proprietary -- Copyright Burdenoff Consultancy Services Pvt. Ltd.

Support

• Issues: GitHub Issues
• Docs: docs.vibecontrols.com