sprocket dev server ​

sprocket dev server is a group of run-management commands built around running Sprocket as an HTTP server, enabling remote workflow submission and monitoring through a REST API. This is useful for scenarios where you want to submit workflows from a separate machine or integrate Sprocket into larger systems.

The group provides the following subcommands:

Overview ​

Server mode provides:

• Remote workflow submission via REST API.
• Real-time monitoring of running workflows.
• Provenance tracking with a SQLite database.
• Concurrent execution of multiple workflows.

The server shares the same execution engine as sprocket run, ensuring consistent behavior between CLI and server-submitted workflows. All evaluations in one server process share backend resource limits and monitoring.

Starting the server ​

sprocket dev server start --allowed-file-paths /path/to/workflows

At least one of --allowed-file-paths or --allowed-urls must be specified to indicate where workflow sources can be loaded from.

Command-line options ​

Configuration ​

Server settings can also be configured in sprocket.toml:

[server]
host = "127.0.0.1"
port = 8080
output_dir = "./out"
allowed_file_paths = ["/path/to/workflows"]
allowed_urls = ["https://raw.githubusercontent.com/"]
allowed_origins = ["http://localhost:3000"]
max_concurrent_runs = 500
orphan_timeout_minutes = 5

[server.database]
url = "sqlite://sprocket.db"

[server.engine]
# Engine configuration (same options as [run] section)

Configuration options ​

Managing runs ​

Once a server is running, you can manage its runs from the command line without talking to the REST API directly. These subcommands connect to the server using the --host and --port options (falling back to the [server] section of your sprocket.toml when not provided). A run may be referenced either by its UUID or by its human-readable generated name (e.g. happy-dolphin-42).

status ​

Show the status of one run, or list all runs when no run is given:

# List all runs
sprocket dev server status

# Show a single run, filter the list, or emit raw JSON
sprocket dev server status happy-dolphin-42
sprocket dev server status --status running --limit 50
sprocket dev server status --json

inspect ​

Show detailed information about a run, including per-status task counts and the output directory. Pass --detailed for a per-task breakdown, or --json for the raw response:

sprocket dev server inspect happy-dolphin-42 --detailed

cancel ​

Cancel a queued or running run:

sprocket dev server cancel happy-dolphin-42

retry ​

Resubmit a previous run, reusing its source, target, and inputs as the base. Any overrides use the same input syntax as submit (key=value, @file, and repeated keys that append to arrays), and take precedence over the original run's values:

sprocket dev server retry happy-dolphin-42 workflow.threads=8

REST API ​

The server exposes a REST API for managing workflow executions, covering server metadata, runs, sessions, and tasks. Interactive documentation is available at /api/v1/swagger-ui while the server is running.

See the REST API reference for every endpoint and for examples of starting a server, submitting a workflow, and checking run status with curl.

Output directory ​

The server uses the same output directory structure as sprocket run. For details on directory layout, provenance database, and output indexing, see the Provenance Tracking documentation.

Security considerations ​

• Always specify --allowed-file-paths or --allowed-urls to restrict which workflow sources can be executed.
• Use --allowed-origins to configure CORS for web-based clients.
• Run behind a reverse proxy with authentication for production deployments.
• The server binds to 127.0.0.1 by default; change to 0.0.0.0 to accept remote connections (not recommended without a reverse proxy).