Quick Start Guide

Flow Sandbox is in preview. The @digitalfrontier/cli package is not published yet, so the commands below describe the intended flow rather than one you can run today. Talk to us if you want access while Flow Sandbox is in preview.

Do not run the install commands below yet. These package names are not reserved, so anything currently published under them is not ours. They document the intended flow; we will announce when they are real.

Flow Sandbox provides an isolated environment for developing, testing, and debugging DigitalFrontier Flow workflows without affecting production systems.

What is Flow Sandbox?

Flow Sandbox is an isolated workflow orchestration environment that lets you:

• Test workflows without affecting production
• Debug issues with detailed execution traces
• Develop faster with instant feedback
• Validate changes before deploying to production
• Replay scenarios to reproduce and fix bugs

Prerequisites

Before you begin, ensure you have:

• A DigitalFrontier Core account
• DigitalFrontier CLI installed (npm install -g @digitalfrontier/cli)
• Basic understanding of DigitalFrontier Flow
• Node.js 18+ or Python 3.8+

Installation

Install DigitalFrontier CLI

npm install -g @digitalfrontier/cli

Authenticate

df login

Create Your First Sandbox

1. Initialize Sandbox

Create a new sandbox environment:

df sandbox create my-first-sandbox

This creates an isolated environment with:

• Dedicated workflow executor
• Isolated state store
• Separate event queue
• Independent metrics

2. Configure Sandbox

Create a sandbox.yaml configuration:

version: 1

sandbox:
  name: my-first-sandbox

  # Execution settings
  execution:
    timeout: 5m
    max_retries: 3
    parallelism: 10

  # State isolation
  state:
    storage: memory  # memory, postgres, redis
    ttl: 24h         # Auto-cleanup after 24 hours

  # Event routing
  events:
    mode: isolated   # isolated, mirror, hybrid

Apply the configuration:

df sandbox apply --config sandbox.yaml

3. Deploy Workflow to Sandbox

Deploy a test workflow:

# workflow.py
from df_flow import Flow

flow = Flow(name="test-workflow")

@flow.task
async def process_data(data: dict):
    """Process incoming data"""
    result = {
        'processed': True,
        'input': data,
        'timestamp': datetime.now().isoformat()
    }
    return result

@flow.task
async def send_notification(result: dict):
    """Send notification about processed data"""
    print(f"Data processed: {result}")
    return result

Deploy to sandbox:

df sandbox deploy \
  --sandbox my-first-sandbox \
  --workflow workflow.py

4. Run Workflow in Sandbox

Execute the workflow:

df sandbox run test-workflow \
  --sandbox my-first-sandbox \
  --input '{"data": "test-value"}'

You'll see real-time execution output:

[12:34:56] Starting workflow: test-workflow
[12:34:56] Task started: process_data
[12:34:57] Task completed: process_data (1.2s)
[12:34:57] Task started: send_notification
[12:34:57] Data processed: {'processed': True, 'input': {'data': 'test-value'}, ...}
[12:34:57] Task completed: send_notification (0.1s)
[12:34:57] Workflow completed successfully (1.3s)

5. Inspect Execution

View detailed execution trace:

df sandbox trace <execution-id>

This shows:

• Task execution timeline
• Input/output for each task
• State changes
• Error details (if any)
• Resource usage

Development Workflow

Local Development

Run sandbox locally for faster iteration:

# Start local sandbox
df sandbox local start

# Deploy workflow
df sandbox local deploy workflow.py

# Run workflow
df sandbox local run test-workflow --input test-data.json

# Watch for changes and auto-reload
df sandbox local watch workflow.py

Testing Workflows

Write tests using the sandbox:

# test_workflow.py
import pytest
from df_flow.testing import SandboxClient

@pytest.fixture
async def sandbox():
    """Create test sandbox"""
    client = SandboxClient("test-sandbox")
    await client.deploy("workflow.py")
    yield client
    await client.cleanup()

async def test_process_data(sandbox):
    """Test data processing workflow"""

    # Run workflow
    result = await sandbox.run(
        "test-workflow",
        input={"data": "test-value"}
    )

    # Assertions
    assert result['status'] == 'completed'
    assert result['output']['processed'] is True
    assert result['duration'] < 5.0  # < 5 seconds

async def test_error_handling(sandbox):
    """Test error handling"""

    # Run with invalid input
    result = await sandbox.run(
        "test-workflow",
        input={"invalid": "data"}
    )

    # Should handle error gracefully
    assert result['status'] == 'failed'
    assert 'error' in result

Run tests:

pytest test_workflow.py

Debugging Workflows

Enable debug mode for detailed logging:

# Run with debug logging
df sandbox run test-workflow \
  --sandbox my-first-sandbox \
  --input test-data.json \
  --debug

# Stream logs in real-time
df sandbox logs my-first-sandbox --follow

# Get execution trace
df sandbox trace <execution-id> --verbose

Sandbox Modes

Isolated Mode (Default)

Complete isolation from production:

sandbox:
  events:
    mode: isolated

• Workflows run in complete isolation
• No interaction with production systems
• Safe for testing breaking changes

Mirror Mode

Mirror production events for testing:

sandbox:
  events:
    mode: mirror
    source: production
    sampling_rate: 0.1  # Mirror 10% of events

• Receive copy of production events
• Test with real data patterns
• Validate changes against live traffic

Hybrid Mode

Combine isolation with selective production integration:

sandbox:
  events:
    mode: hybrid
    sources:
      - type: isolated
        weight: 70
      - type: mirror
        source: production
        weight: 30
        sampling_rate: 0.5

Environment Management

Create Multiple Sandboxes

Create sandboxes for different purposes:

# Development sandbox
df sandbox create dev-sandbox --config dev.yaml

# Staging sandbox
df sandbox create staging-sandbox --config staging.yaml

# Testing sandbox
df sandbox create test-sandbox --config test.yaml

List Sandboxes

df sandbox list

Output:

NAME              STATUS    CREATED          WORKFLOWS
dev-sandbox       running   2 hours ago      3
staging-sandbox   running   1 day ago        5
test-sandbox      stopped   1 week ago       2

Switch Between Sandboxes

# Set default sandbox
df sandbox use dev-sandbox

# Run command in specific sandbox
df sandbox run workflow --sandbox staging-sandbox

Data Management

Reset Sandbox State

Clear all state and start fresh:

df sandbox reset my-first-sandbox

Export Sandbox Data

Export workflow executions for analysis:

df sandbox export my-first-sandbox \
  --format json \
  --output sandbox-data.json

Import Test Data

Load test data into sandbox:

df sandbox import my-first-sandbox \
  --file test-data.json

Integration with CI/CD

GitHub Actions

# .github/workflows/test-workflows.yml
name: Test Workflows

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install Digital Frontier CLI
        run: npm install -g @digitalfrontier/cli

      - name: Authenticate
        run: df login --token ${{ secrets.DF_TOKEN }}

      - name: Create test sandbox
        run: df sandbox create ci-${{ github.run_id }}

      - name: Deploy workflows
        run: df sandbox deploy --sandbox ci-${{ github.run_id }} .

      - name: Run tests
        run: pytest tests/

      - name: Cleanup sandbox
        if: always()
        run: df sandbox delete ci-${{ github.run_id }}

Best Practices

1. Use Descriptive Names

# Good
df sandbox create feature-user-auth
df sandbox create bugfix-payment-retry

# Bad
df sandbox create test1
df sandbox create sandbox2

2. Set Resource Limits

sandbox:
  resources:
    max_executions: 1000
    max_duration: 1h
    max_memory: 512MB

3. Auto-Cleanup

sandbox:
  cleanup:
    enabled: true
    after: 24h  # Delete sandbox after 24 hours of inactivity

4. Use Version Control

# Save sandbox configuration
df sandbox export-config my-sandbox > sandbox.yaml

# Commit to git
git add sandbox.yaml
git commit -m "Add sandbox configuration"

Next Steps

• Learn about sandbox features
• Explore advanced examples
• Learn about DigitalFrontier Flow

Troubleshooting

Sandbox won't start

Check resource quotas:

df sandbox quota

Workflows fail in sandbox but work in production

Compare configurations:

df sandbox diff my-sandbox production

Slow execution in sandbox

Increase parallelism:

sandbox:
  execution:
    parallelism: 20  # Increase from default

Getting Help

• Email us at support@digitalfrontier.so
• Check the Flow Sandbox documentation
• Contact support at support@digitalfrontier.so