Skip to main content

Python SDK

The official Python SDK for VibeControls provides async/await access to the full GraphQL API.

Install​

pip install vibecontrols-sdk

Development install:

git clone https://github.com/algoshred/vibecontrols-sdk-python.git
cd vibecontrols-sdk-python
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

Environment selection​

The SDK endpoint defaults to production. Select a different environment by passing the appropriate endpoint in VibeControlsConfig:

EnvironmentWorkspace endpointGlobal endpoint
prod (default)https://graphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://graphql.burdenoff.com/global/graphql
alphahttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://alphagraphql.burdenoff.com/global/graphql
localhttp://localhost:4003/workspaces/graphqlhttp://localhost:4000/global/graphql

Set BURDENOFF_ENV=local|alpha|prod in your shell if your app consumes it to choose endpoints, or pass them explicitly to VibeControlsConfig.

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()
    for v in vibes:
        print(f"Vibe: {v['name']} ({v['type']})")

    # List sessions
    sessions = await sdk.sessions.list()
    for s in sessions:
        print(f"Session: {s['name']} — {s['status']}")

    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
)

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(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="my-service",
    client_secret="secret",
)
sdk = VibeControlsSDK(config)
# Tokens are obtained automatically on first request

Modules​

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

ModulePropertyDescription
Authsdk.authSign in/up, sign out, token refresh, device code, PKCE, client credentials
Agentssdk.agentsAgent CRUD, heartbeat, probes, plugin management
Vibessdk.vibesVibe (project/workspace) CRUD and management
Sessionssdk.sessionsTerminal session management
Notessdk.notesNote CRUD operations
Configurationsdk.configurationKey-value configuration management
Webhookssdk.webhooksWebhook CRUD and management
Docssdk.docsDocumentation site management
VibeDecksdk.vibedeckVibeDeck management (decks and buttons)
Targetssdk.targetsTarget machine management
Auditsdk.auditAudit log queries
UI Sessionsdk.ui_sessionUI session state management
Tunnelssdk.tunnelsAgent tunnel management
AI Tool Eventssdk.ai_tool_eventsAI tool event tracking

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}")

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

# Build
python -m build

Source​

  • Repository: github.com/algoshred/vibecontrols-sdk-python
  • Package: vibecontrols-sdk on PyPI

Next steps​