Local Development

Develop workflows locally using the Bifrost SDK and CLI. No Docker required - connect directly to your Bifrost instance.

Prerequisites

• Python 3.11+ installed
• Access to a Bifrost instance (cloud or self-hosted)

Quick Start

1. Install the Bifrost SDK:

   pip install bifrost-sdk

2. Set your Bifrost API URL (create a .env file or export):

   export BIFROST_API_URL=https://your-bifrost-instance.com

3. Start developing - authentication happens automatically on first SDK call

Tip

The SDK auto-authenticates using device code flow. Your browser opens, you enter a code, and credentials are saved to ~/.bifrost/credentials.json.

How Authentication Works

When you first use the SDK, it automatically triggers device authorization:

1. SDK detects no credentials exist
2. Opens your browser to verification page
3. You enter the displayed code and authenticate
4. Credentials saved locally with auto-refresh

Tokens refresh automatically when expired. Run bifrost logout to clear credentials.

Creating Workflows

Create Python files locally and test them before uploading:

from bifrost import workflow, context

@workflow
async def hello_world(name: str):
    """A simple example workflow."""
    return {"message": f"Hello, {name}!", "org": context.org_id}

Use the web UI editor to upload, or sync via the API.

Using SDK Features Locally

All SDK modules work in local development:

from bifrost import ai, knowledge, config

# AI completions
response = await ai.complete("Summarize this ticket")

# Knowledge store
await knowledge.store("Policy content...", namespace="policies")
results = await knowledge.search("refund policy", namespace="policies")

# Configuration
api_key = await config.get("external_api_key")

IDE Setup

VS Code

Install the Python extension and configure your interpreter to the venv with bifrost-sdk installed. The SDK provides full type hints.

Environment Variables

Create a .env file in your project root:

BIFROST_API_URL=https://your-bifrost-instance.com

The SDK loads .env automatically via python-dotenv if installed.

Self-Hosted Development

For contributors developing the platform itself, use Docker Compose:

1. Clone the repository:

   git clone https://github.com/jackmusick/bifrost.git
   cd bifrost

2. Start with hot reload:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up

3. Access at http://localhost:3000

Service	Dev Behavior
api	Hot reload with uvicorn, debugpy on port 5678
worker	Auto-restart on code changes
client	Vite dev server with HMR

Next Steps

Writing Workflows

Learn workflow development

AI Coding Guide

Use AI to write workflows

SDK Reference

Explore the SDK