Skip to content

First local workflow

Start with a small local task: send an analysis to a named worker and read its report. These are the same operations a delegated child uses; no cloud account or model subscription is needed. To start with parent/child access instead, run the delegation example. The same workflow can be driven from your terminal or by an MCP-connected agent.

Run the analysis

Assume inputs contains sales.csv and analyze.py, worker has Python, and reports is writable. With these resources defined in ./ridge.yaml, the workflow is entirely Ridge commands:

ridge resources
ridge copy inputs:sales.csv worker:sales.csv
ridge copy inputs:analyze.py worker:analyze.py
ridge exec worker --timeout 30 -- python3 analyze.py
# After a successful exit:
ridge copy worker:report.csv reports:report.csv
ridge read reports report.csv

Both execution and the final read print:

region,revenue
East,100.00
West,200.00

The input files remain unchanged; the worker and reports resource each contain the generated report. Rerunning the copy/analysis steps replaces their exact destinations. Need a ready-to-run setup? The steps below provide these inputs and three local resources, without a cloud account or Docker.

Install

Install uv, then create and activate an environment with Python 3.11 or newer. These commands use a POSIX shell (macOS or Linux):

uv venv --python 3.11
. .venv/bin/activate
uv pip install ridge-core
ridge --help

The distribution is named ridge-core; the import and command are ridge. In a uv-managed Python project, use uv add ridge-core. For development instead, use uv sync and . .venv/bin/activate. Keep the environment active so ridge and python3 are available on PATH.

Create the demo workspace

The demo assets live in the source repository. Clone https://github.com/vasinov/ridge-core.git if needed, then run the following from the checkout root, using a fresh ridge-demo directory. To match an installed release, check out its vX.Y.Z tag before copying the assets. The bundled inventory defines inputs, worker, and reports as local resources. Together with its policy and managed state, this configuration defines a Ridge workspace. Create every root before discovery.

mkdir -p ridge-demo/inputs ridge-demo/worker ridge-demo/reports
cp docs/examples/assets/ridge.yaml ridge-demo/ridge.yaml
cp docs/examples/assets/sales.csv docs/examples/assets/analyze.py ridge-demo/inputs/
cd ridge-demo

Now run the analysis commands above. The analysis script uses Python's standard library and decimal arithmetic; the input contains four sales.

What the resource names buy you

The caller chooses locations and operations, not backend transfer commands. Every resource is local here to keep the first run reproducible. Change the worker to a container or SSH host and the caller's workflow stays the same.

ridge resources shows supported and allowed operations. Inputs have data-only read grants; the worker allows execution and data access. Use ridge inspect worker for detailed properties. See Authorization.

Ridge loads ./ridge.yaml by default. Use ridge --config PATH COMMAND or RIDGE_CONFIG to select a workspace's configuration. Relative roots resolve from the configuration file, not the invocation directory.

Platform expectations

Ridge requires Python 3.11+ on a POSIX host. The test workflow covers Python 3.11–3.14 on Linux and Python 3.14 on macOS. Jobs additionally require local advisory locks and a compatible ps; see job prerequisites. Docker/SSH workers require Python 3.11 or newer. See Development for verification and external-test prerequisites.

Next steps