Run On
Stoobly Scaffold Runtime Options - Questions & Answers
The --run-on option when creating a scaffold app determines whether workflows run locally on your machine or in Docker containers. This provides flexibility for different development environments and team preferences.
Understanding Runtime Options
Q: What runtime options are available for scaffold apps?
A: Scaffold supports two runtime options: docker (containerized execution) and local (native execution on your machine). You can configure one or both.
Example:
# Docker only (default)
stoobly-agent scaffold app create my-app --run-on docker
# Local only
stoobly-agent scaffold app create my-app --run-on local
# Both Docker and local
stoobly-agent scaffold app create my-app --run-on docker --run-on localQ: What's the difference between Docker and local runtime?
A: Docker runtime runs workflows in isolated containers with consistent environments, while local runtime executes workflows directly on your machine using your installed Python and dependencies.
Example:
Q: Which runtime option should I choose?
A: Use Docker for team consistency and isolation, or local for faster iteration and simpler setup. You can enable both to support different team member preferences.
Example:
Docker Runtime
Q: What are the benefits of using Docker runtime?
A: Docker provides environment consistency across team members, dependency isolation, easy cleanup, and works the same on all operating systems.
Example:
Q: What are the requirements for Docker runtime?
A: You need Docker installed and running on your machine. The Docker daemon must be accessible.
Example:
Q: How do I specify a custom Docker socket path?
A: Use the --docker-socket-path option when creating the app.
Example:
Q: How do Docker-based workflows work?
A: Docker workflows use docker-compose to orchestrate containers for stoobly-agent, your services, and any dependencies, providing complete isolation.
Example:
Q: Can I use Docker runtime on Windows, Mac, and Linux?
A: Yes, Docker runtime works consistently across all platforms as long as Docker Desktop (Windows/Mac) or Docker Engine (Linux) is installed.
Example:
Q: How do I troubleshoot Docker runtime issues?
A: Check Docker is running, verify permissions, and review container logs.
Example:
Local Runtime
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:
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:
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:
Supporting Both Runtimes
Q: Why would I enable both Docker and local runtimes?
A: Enabling both allows team members to choose their preferred runtime based on their environment, while maintaining compatibility.
Example:
Q: How do I create a scaffold that supports both runtimes?
A: Specify both --run-on docker and --run-on local when creating the app.
Example:
Q: Do both runtimes use the same configuration?
A: Yes, both runtimes share the same service configurations, workflows, and recorded data.
Example:
Q: Can I switch between Docker and local runtime after creating the app?
A: Yes, you can manually update the app configuration or recreate the app with different runtime options.
Example:
Runtime-Specific Workflows
Q: How do I explicitly use Docker runtime for a workflow?
A: Use the Makefile commands, which are configured for Docker execution.
Example:
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 force a specific runtime when both are configured?
A: The Makefile uses Docker by default. For local, use the CLI commands directly.
Example:
Performance Considerations
Q: Which runtime is faster for development?
A: Local runtime typically has faster startup times, while Docker provides better isolation and consistency.
Example:
Q: Does Docker runtime use more resources?
A: Yes, Docker adds overhead for containerization, but provides better isolation and cleanup.
Example:
Q: How do I optimize Docker runtime performance?
A: Use local Docker images, enable BuildKit, and allocate sufficient resources to Docker.
Example:
Team Collaboration with Different Runtimes
Q: How do I set up a project that works for team members with different preferences?
A: Enable both runtimes and document both approaches in your README.
Example:
Q: How do I ensure consistency when team members use different runtimes?
A: Use the same service configurations and share recorded data via version control.
Example:
Q: Can Docker and local users work on the same project simultaneously?
A: Yes, but they should use different workflow namespaces to avoid conflicts.
Example:
CI/CD with Runtime Options
Q: Which runtime should I use in CI/CD?
A: Docker is recommended for CI/CD as it provides consistent, isolated environments.
Example:
Q: Can I use local runtime in CI/CD?
A: Yes, if your CI environment has Python and stoobly-agent installed, local runtime can be faster.
Example:
Q: How do I test both runtimes in CI/CD?
A: Create separate CI jobs for Docker and local runtimes.
Example:
Migration Between Runtimes
Q: How do I migrate from Docker to local runtime?
A: Update the app configuration to include local runtime and use CLI commands instead of Makefile.
Example:
Q: How do I migrate from local to Docker runtime?
A: Update the app configuration to include Docker runtime and start using Makefile commands.
Example:
Q: Will my recorded data work with both runtimes?
A: Yes, recorded data is stored in .stoobly/ and works with both runtimes.
Example:
Quick Reference
Q: What's a quick comparison of Docker vs Local runtime?
A: Here's a side-by-side comparison:
Docker Runtime:
✅ Consistent across all environments
✅ Complete isolation
✅ Easy cleanup
✅ Works on Windows, Mac, Linux
❌ Slower startup
❌ Requires Docker installed
❌ More resource usage
Local Runtime:
✅ Faster startup
✅ Simpler debugging
✅ Less resource usage
✅ No Docker required
❌ Requires Python 3.10+
❌ Less isolation
❌ Environment differences possible
Example:
Q: What's the recommended setup for a new team project?
A: Enable both runtimes to support different team member preferences and environments.
Example:
Last updated
Was this helpful?