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
• pipx recommended for CLI installation (or pip)
• Access to a Bifrost instance (cloud or self-hosted)

Quick Start

1. Install the Bifrost CLI:

   The SDK is served directly from your Bifrost instance:

   pipx install https://your-instance.gobifrost.com/api/cli/download

   Or with pip:

   pip install https://your-instance.gobifrost.com/api/cli/download

   Verify the installation:

   bifrost help

2. Authenticate:

   bifrost login --url https://your-instance.gobifrost.com

   This opens your browser for authentication. Credentials are saved to ~/.bifrost/credentials.json and refresh automatically.

3. Start developing - write workflows locally and test them against your instance

Tip

Replace https://your-instance.gobifrost.com with your actual Bifrost URL. Every instance has a unique URL provided by your organization.

Creating Workflows

Create Python files locally and test them with the CLI:

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}

Test locally:

bifrost run hello_world.py hello_world --params '{"name": "Alice"}'

Sync to the platform:

bifrost watch

This watches your workspace and auto-syncs every file change. Keep it running while you develop.

Using SDK Features Locally

All SDK modules work in local development - they call the remote API using your saved credentials:

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 environment with the Bifrost SDK installed. The SDK provides full type hints.

Managing Credentials

bifrost login --url https://your-instance.gobifrost.com  # Authenticate
bifrost logout                                            # Clear credentials

Tokens refresh automatically when expired. If refresh fails (e.g., password changed), run bifrost login again.

Self-Hosted Development

For contributors developing the platform itself, use Docker Compose:

1. Clone the repository:

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

2. Run setup and start with hot reload:

   ./setup.sh
   ./debug.sh

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-Assisted Development

Use AI tools to build workflows

SDK Reference

Explore the SDK