External SDK

External SDK

The Bifrost SDK can be installed and used outside of the platform for external development, testing, and automation scripts.

Installation

Install directly from your Bifrost instance:

pip install https://your-bifrost-instance.com/api/sdk/download

For local development:

pip install http://localhost:3000/api/sdk/download

Configuration

Set environment variables to connect to your Bifrost instance:

export BIFROST_DEV_URL=https://your-bifrost-instance.com
export BIFROST_DEV_KEY=bfsk_xxxxxxxxxxxx

Or use a .env file:

BIFROST_DEV_URL=https://your-bifrost-instance.com
BIFROST_DEV_KEY=bfsk_xxxxxxxxxxxx

Getting an API Key

1. Go to Settings → Developer Settings in the Bifrost UI

2. Click Create API Key

3. Give it a name and optional expiration

4. Copy the key (shown only once) - it starts with bfsk_

Caution

API keys are shown only once when created. Store them securely.

Usage

File Operations

from bifrost import files

# Write a file
await files.write("data/output.txt", "Hello from external SDK!")

# Read a file
content = await files.read("data/output.txt")
print(content)

# List files
items = await files.list("data/")
for item in items:
    print(item)

# Check if file exists
if await files.exists("data/config.json"):
    config = await files.read("data/config.json")

# Delete a file
await files.delete("data/old-file.txt")

Config Operations

Config operations are async:

import asyncio
from bifrost import config

async def main():
    # Get a config value
    value = await config.get("api_url")
    print(f"API URL: {value}")

    # Set a config value
    await config.set("my_setting", "my_value")

    # Set a secret (encrypted)
    await config.set("api_key", "secret123", is_secret=True)

    # List all config
    all_config = await config.list()
    print(all_config)

    # Delete a config
    await config.delete("old_setting")

asyncio.run(main())

Using the Client Directly

For more control, use the BifrostClient:

from bifrost import get_client

client = get_client()

# Get developer context
context = client.get_context()
print(f"User: {context['user']['email']}")
print(f"Org: {context['organization']['name']}")

Developer Context

Configure your default organization and parameters in Settings → Developer Settings:

• Default Organization: SDK operations use this org context
• Default Parameters: Pre-fill workflow parameters for testing
• Track Executions: Whether to log executions in history

Example: Automation Script

#!/usr/bin/env python3
"""
External automation script using Bifrost SDK.
"""
import asyncio
import json
from bifrost import files, config

async def sync_data():
    """Sync external data to Bifrost workspace."""

    # Get API endpoint from config
    api_url = await config.get("external_api_url")

    # Fetch external data (using your own HTTP client)
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{api_url}/data")
        data = response.json()

    # Write to Bifrost workspace
    await files.write(
        "data/external-sync.json",
        json.dumps(data, indent=2)
    )

    print(f"Synced {len(data)} records to workspace")

if __name__ == "__main__":
    asyncio.run(sync_data())

Differences from Internal SDK

When running inside a workflow vs externally:

Feature	Internal (Workflow)	External (SDK)
Context	Full execution context	Developer context only
Auth	Automatic	API key required
File ops	Direct filesystem	API calls
Config	Cached + buffered writes	Direct API calls
OAuth	Full token access	Not available

Note

OAuth operations (oauth.get()) are not available in the external SDK - they require workflow execution context.

VS Code Integration

Add this to your .vscode/launch.json to run workflows directly:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Workflow",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env",
      "env": {
        "BIFROST_DEV_URL": "http://localhost:3000",
        "BIFROST_DEV_KEY": "bfsk_your_key_here"
      }
    }
  ]
}

Then add a test block to your workflow files:

from bifrost import workflow, context, files

@workflow
async def process_data(name: str, count: int = 1):
    """Process some data."""
    # Your workflow logic
    result = await files.read("config.json")
    return {"name": name, "count": count, "config": result}


# Test block - runs when you execute the file directly
if __name__ == "__main__":
    import asyncio
    from bifrost import get_client

    async def test():
        client = get_client()
        print(f"Connected as: {client.user['email']}")
        print(f"Organization: {client.organization}")

        # Execute the workflow via API
        response = await client.post(
            "/api/workflows/execute",
            json={
                "workflow_id": "process_data",
                "input_data": {"name": "test", "count": 5}
            }
        )
        print(f"Result: {response.json()}")

    asyncio.run(test())

Now press F5 in VS Code to run and debug your workflow.

Tip

The test block only runs when executing the file directly - it’s ignored when Bifrost imports your workflow.

Troubleshooting

”Invalid or expired API key”

1. Verify your API key starts with bfsk_
2. Check the key hasn’t expired in Developer Settings
3. Ensure BIFROST_DEV_KEY environment variable is set

”Connection refused”

1. Verify BIFROST_DEV_URL is set correctly
2. Check the Bifrost instance is running
3. For local dev, use http://localhost:3000

Files not appearing

1. Check your default organization in Developer Settings
2. Verify you have permissions to the organization
3. Files are org-scoped - ensure you’re looking in the right org