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("user@example.com", "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.

Authentication Flows

Email / Password

auth = await sdk.auth.sign_in("user@example.com", "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("user@example.com", "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