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 -w hello_world -p '{"name": "Alice"}'

Sync to the platform:

bifrost sync

This opens an interactive TUI where you can review entity changes (workflows, forms, agents, etc.) and file differences between local and remote. For each item, you can choose to push, pull, delete, or skip with smart defaults based on timestamps.

bifrost push and bifrost pull are available as convenience aliases that default to their respective directions.

Registering workflows

Pushing a .py file uploads it but does not make a @workflow, @tool, or @data_provider discoverable in the platform DB. Register the function explicitly so it can be referenced by forms, agents, and event subscriptions:

bifrost workflows register --path workflows/billing.py --function-name run

Pass --org <ref> to scope the workflow to a specific organization. To list orphaned entries (file moved or deleted), run bifrost workflows list-orphaned; to repoint one, use bifrost workflows replace.

Watch mode

For continuous development, use watch mode:

bifrost watch

This watches the workspace and auto-pushes every saved file. Keep it running while you develop. The watch TUI shows structured log columns (time, action, path, user) with color coding.

--mirror

By default, bifrost watch (and push/sync) only push files you’ve changed locally. Adding --mirror makes the platform side match your local directory exactly — files present on the platform but missing locally are deleted. Use it when you’ve renamed or removed files and want the platform to reflect that, but understand it’s destructive on the remote.

bifrost watch apps/my-app --mirror

Calling arbitrary API endpoints

For anything the typed CLI commands don’t yet wrap, bifrost api sends an authenticated request to any endpoint:

bifrost api GET /api/workflows
bifrost api POST /api/applications/my-app/validate
bifrost api POST /api/files/push @payload.json   # @file = read JSON body from file

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

CLI Cheatsheet

Every bifrost command in one page

Writing Workflows

Learn workflow development

AI-Assisted Development

Use AI tools to build workflows

SDK Reference

Explore the SDK