Stoobly Scaffold Local Runtime - Questions & Answers
This document covers local runtime-specific options for Stoobly scaffold. For general runtime topics, see README.md. For Docker runtime, see docker.md.
Local Runtime Overview
Q: What are the benefits of using local runtime?
A: Local runtime offers faster startup times, simpler debugging, direct access to your filesystem, and no Docker dependency.
Example:
stoobly-agentscaffoldappcreatemy-app--runtimelocal# Faster startup, no container overheadstoobly-agentscaffoldworkflowuptest
Q: What are the requirements for local runtime?
A: You need Python 3.10, 3.11, or 3.12 installed, and stoobly-agent installed via pipx.
Example:
# Verify Python versionpython3--version# Should be 3.10, 3.11, or 3.12# Install stoobly-agentpipxinstallstoobly-agent# Create local runtime scaffoldstoobly-agentscaffoldappcreatemy-app--runtimelocal
Q: How do local workflows work?
A: Local workflows run stoobly-agent directly on your machine, proxying requests to your services without containerization.
Example:
Q: Can I use local runtime if my services are in Docker?
A: Yes, local runtime only affects how stoobly-agent runs. Your services can still run in Docker containers.
Example:
Q: How do I troubleshoot local runtime issues?
A: Check Python version, verify stoobly-agent installation, and review logs.
Example:
Local Workflows
Q: How do I explicitly use local runtime for a workflow?
A: Use the stoobly-agent scaffold workflow commands directly.
Example:
Q: How do I use local runtime?
A: Create the app with --runtime local (or use default) and use CLI commands for workflows.
Example:
Local Migration
Q: How do I migrate from Docker to local runtime?
A: Recreate the app with local runtime and use CLI commands instead of Makefile.
Example:
Getting Started with Local Runtime Commands
Q: How do I run workflow commands with local runtime?
A: Use stoobly-agent scaffold workflow commands directly. No Makefile is needed for local runtime.
Example:
Recording Workflow
Q: How do I start a recording workflow with local runtime?
A: Use stoobly-agent scaffold workflow up record to start the recording workflow, which sets up the proxy to capture HTTP requests. Use stoobly-agent intercept enable to enable intercept to start recording.
Example:
Q: How do I stop a recording workflow with local runtime?
A: Use stoobly-agent scaffold workflow down record to stop and clean up the recording workflow.
Example:
Q: How do I view logs from the recording workflow with local runtime?
A: View logs from the workflow directory or use Stoobly agent commands.
Example:
Q: How do I list services in the recording workflow with local runtime?
A: Use stoobly-agent scaffold workflow services to display all configured services.
Example:
Q: How do I view the recorded requests report with local runtime?
A: Use stoobly-agent request list to display all intercepted and recorded requests.
Example:
Mock Workflow
Q: How do I start a mock workflow with local runtime?
A: Use stoobly-agent scaffold workflow up mock to start the mock workflow, which serves mocked responses based on recorded data.
Example:
Q: How do I stop a mock workflow with local runtime?
A: Use stoobly-agent scaffold workflow down mock to stop and clean up the mock workflow.
Example:
Q: How do I view logs from the mock workflow with local runtime?
A: View logs from the workflow directory or use Stoobly agent commands.
Example:
Q: How do I list services in the mock workflow with local runtime?
A: Use stoobly-agent scaffold workflow services to display all configured services.
Example:
Q: How do I view the mock requests report with local runtime?
A: Use stoobly-agent request list to display a list of all mocked requests.
Example:
Test Workflow
Q: How do I start a test workflow with local runtime?
A: Use stoobly-agent scaffold workflow up test to start the test workflow, which runs automated tests against your services.
Example:
Q: How do I stop a test workflow with local runtime?
A: Use stoobly-agent scaffold workflow down test to stop and clean up the test workflow.
Example:
Q: How do I view logs from the test workflow with local runtime?
A: View logs from the workflow directory or use Stoobly agent commands.
Example:
Q: How do I list services in the test workflow with local runtime?
A: Use stoobly-agent scaffold workflow services to display all configured services.
Example:
Q: How do I view the test requests report with local runtime?
A: Use stoobly-agent request list to display a list of all test requests and results.
Example:
Scenario Management
Q: How do I create a scenario with local runtime?
A: Use stoobly-agent scenario create to create a new scenario.
Example:
Q: How do I list all scenarios with local runtime?
A: Use stoobly-agent scenario list to display all available scenarios.
Example:
Q: How do I delete a scenario with local runtime?
A: Use stoobly-agent scenario delete to delete a specific scenario.
Example:
Q: How do I snapshot a scenario with local runtime?
A: Use stoobly-agent scenario snapshot to create committable files for a scenario.
Example:
Q: How do I reset a scenario to its snapshot state with local runtime?
A: Use stoobly-agent scenario reset to restore a scenario from its snapshot.
Example:
Q: How do I overwrite a scenario with local runtime?
A: Use stoobly-agent scenario overwrite to overwrite an existing scenario.
Example:
Certificate Management
Q: How do I install the CA certificate with local runtime?
A: Use stoobly-agent ca-cert install to install the CA certificate.
Example:
Q: How do I skip the CA certificate installation prompt with local runtime?
A: Set the STOOBLY_CA_CERTS_INSTALL_CONFIRM environment variable to y before running the workflow.
Example:
Hostname Management
Q: How do I skip the hostname installation prompt with local runtime?
A: Set the STOOBLY_HOSTNAME_INSTALL_CONFIRM environment variable to y to automatically confirm hostname installation.
Example:
Q: How do I prevent hostname installation with local runtime?
A: Set the STOOBLY_HOSTNAME_INSTALL_CONFIRM environment variable to n to skip hostname installation.
Example:
Intercept Management
Q: How do I enable intercept mode with local runtime?
A: Use stoobly-agent intercept enable with an optional scenario key to enable request interception.
Example:
Q: How do I disable intercept mode with local runtime?
A: Use stoobly-agent intercept disable to turn off request interception.
Example:
Environment Variables & Configuration
Q: How do I specify a custom application directory with local runtime?
A: Use the --app-dir-path option when running workflow commands.
Example:
Q: How do I use a custom .env file with workflows in local runtime?
A: Set the STOOBLY_DOTENV_FILE environment variable to specify your .env file path.
Example:
Q: How do I specify custom CA certificate directory with local runtime?
A: Use the --ca-certs-dir-path option when running workflow commands.
Example:
Q: How do I pass additional service options to workflows with local runtime?
A: Use the --service option multiple times or pass options directly to the workflow command.
Example:
Q: How do I specify a custom context directory with local runtime?
A: Use the --context-dir-path option when running workflow commands.
Example:
Advanced Workflow Options
Q: How do I pass additional options to workflow up commands with local runtime?
A: Add options directly to the stoobly-agent scaffold workflow up command.
Example:
Q: How do I run a workflow with a custom namespace with local runtime?
A: Use the --namespace option to specify a custom workflow namespace.
Note: Namespaces are only supported by test workflows and custom workflows based on the test workflow template. Record and mock workflows do not support namespaces.
Example:
Q: How do I filter services when starting a workflow with local runtime?
A: Use the --service option to specify which services to include.
Example:
Combining Multiple Options
Q: How do I run a fully automated workflow without any prompts with local runtime?
A: Set both hostname and CA certificate confirmation environment variables before running the workflow.
Example:
Q: How do I run a workflow with custom directories and environment with local runtime?
A: Use command-line options and environment variables together to customize all aspects of the workflow.
Example:
Local Runtime Troubleshooting
Q: How do I check if stoobly-agent is installed?
A: Run stoobly-agent --version to verify installation.
Example:
Q: How do I verify Python version compatibility?
A: Run python3 --version to check if you have Python 3.10, 3.11, or 3.12.
Example:
Q: What do I do if pipx is not installed?
A: Install pipx using your system package manager or Python pip.
Example:
Q: How do I view what services are configured with local runtime?
A: Use the workflow-specific services command to list all configured services.
Example:
Q: How do I validate my service configuration?
A: Use scaffold service show to view the current configuration.
Example:
Q: What do I do if a workflow fails to start?
A: Check the logs for errors and verify service configurations.
Example:
Quick Reference
Q: What are the most common local runtime commands I'll use?
A: Here's a quick reference of the most frequently used commands:
Example:
Q: How do I create an alias for easier command usage with local runtime?
A: Add an alias to your shell configuration file for convenience.
# Create local runtime app
stoobly-agent scaffold app create my-app --runtime local
# Create service
stoobly-agent scaffold service create my-service
# Start workflow (runs locally)
stoobly-agent scaffold workflow up test
# Stoobly runs locally, services in Docker
stoobly-agent scaffold app create my-app --runtime local
# Add service that runs in Docker
stoobly-agent scaffold service create api \
--hostname api.local \
--upstream-hostname localhost \
--upstream-port 8080
# Start your service in Docker
docker run -p 8080:8080 my-api-image
# Start stoobly workflow locally
stoobly-agent scaffold workflow up test
# Check Python version
python3 --version
# Verify stoobly-agent
stoobly-agent --version
# Check logs with verbose output
stoobly-agent scaffold workflow up test \
--log-level debug
# Local runtime via CLI
stoobly-agent scaffold workflow up record
stoobly-agent scaffold workflow up mock
stoobly-agent scaffold workflow up test
# App created with local runtime (default)
stoobly-agent scaffold app create my-app
stoobly-agent scaffold service create my-service
# Currently using Docker
# Recreate with local runtime
stoobly-agent scaffold app create my-app --runtime local
# Now use local runtime commands
stoobly-agent scaffold service create my-service
# Start a workflow
stoobly-agent scaffold workflow up test
# Stop a workflow
stoobly-agent scaffold workflow down test
stoobly-agent scaffold workflow up record
stoobly-agent intercept enable
stoobly-agent scaffold workflow down record
# View logs from workflow directory
cat .stoobly/tmp/record/logs/requests.json
# Or use Stoobly agent commands
stoobly-agent request list
stoobly-agent scaffold workflow services record
stoobly-agent request list
stoobly-agent scaffold workflow up mock
stoobly-agent scaffold workflow down mock
# View logs from workflow directory
cat .stoobly/tmp/mock/logs/requests.json
# Or use Stoobly agent commands
stoobly-agent request list
stoobly-agent scaffold workflow services mock
stoobly-agent request list
stoobly-agent scaffold workflow up test
stoobly-agent scaffold workflow down test
# View logs from workflow directory
cat .stoobly/tmp/test/logs/requests.json
# Or use Stoobly agent commands
stoobly-agent request list
stoobly-agent scaffold workflow services test
stoobly-agent request list
stoobly-agent scenario create "User Login Flow"
stoobly-agent scenario list
stoobly-agent scenario delete <SCENARIO-KEY>
stoobly-agent scenario snapshot <SCENARIO-KEY>
stoobly-agent scenario reset <SCENARIO-KEY>
stoobly-agent scenario overwrite <SCENARIO-KEY>
stoobly-agent ca-cert install
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
stoobly-agent scaffold workflow up test
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
stoobly-agent scaffold workflow up test
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=n
stoobly-agent scaffold workflow up mock
