.. _local_compute-label:

Local Compute: Running Scaleout Edge Clients With Local Code
=============================================================

Scaleout Edge supports two primary modes of client execution: **Local Compute** (default, where the client runs its own code) and **Remote Compute** (where the client downloads and runs a package from the server).

Local Compute is the default mode and gives you full control over the execution environment — useful for debugging, integrating with proprietary local data pipelines, or operating in environments where downloading code is restricted. Remote Compute (via ``--remote-package``) is the opt-in mode used when you want to distribute code automatically to a fleet of clients.

How the Two Modes Work
-----------------------

In Local Compute mode (default), the client connects to the network but executes logic defined in the local ``client`` folder. In Remote Compute mode (``--remote-package``), the Control Plane distributes a Compute Package to the edge node, which downloads and extracts it on startup.

Key Differences
~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 35 40

   * - Feature
     - Local Compute (Default)
     - Remote Compute (``--remote-package``)
   * - Code Source
     - Local Filesystem
     - Downloaded from Control Plane
   * - Versioning
     - Managed by User (Git/Local)
     - Managed by Registry
   * - Environment
     - User-managed (local python/conda)
     - Auto-provisioned (venv/Docker)
   * - Best For
     - R&D, Debugging, strict Security
     - Production Fleets, Consistency

Setting Up Local Compute
-------------------------

1. Define Your Client Logic
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a local directory with your project structure (as defined in Project Structure).

.. code-block:: text

    my-local-project/
    ├── scaleout.yaml
    ├── train.py
    ├── validate.py
    └── model.py

2. Start the Client
~~~~~~~~~~~~~~~~~~~~

Since local package mode is the default, no extra flag is needed. Navigate to your project root (where the ``client`` folder lives) and start the client:

.. code-block:: bash

    scaleout client start \
        --api-url <your-api-url> \
        --token <your-token>

The client will connect to the Combiner and wait for training requests. When a request arrives it will execute the ``train`` command defined in your local ``scaleout.yaml``.

Distributing Code with ``--remote-package``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

During R&D it is common to iterate quickly and test across a fleet of clients. Manually staging updated code on every node becomes a bottleneck. The ``--remote-package`` flag solves this: the client downloads and extracts the compute package directly from the server on startup, so every client always runs the same version of your code.

.. code-block:: bash

    scaleout client start \
        --api-url <your-api-url> \
        --token <your-token> \
        --remote-package

Using ``--remote-package`` automatically enables the managed Python environment, meaning the client also provisions the Python environment declared in the package. This makes it straightforward to roll out dependency updates alongside code changes without touching each node manually.

To opt out of the managed environment while still using a remote package, pass ``--disable-managed-env``:

.. code-block:: bash

    scaleout client start \
        --api-url <your-api-url> \
        --token <your-token> \
        --remote-package \
        --disable-managed-env

Development Workflow
--------------------

Local Compute is the fastest way to iterate on model code:

1. **Edit**: Modify ``train.py`` or ``model.py`` locally.
2. **Restart**: Restart the scaleout client process (or use a hot-reload script).
3. **Test**: Trigger a new round from the Control Plane.
4. **Debug**: View stdout/stderr logs directly in your terminal without latency.

Security Implications
---------------------

Using Local Compute shifts the security responsibility. Since the Control Plane cannot verify the code running on the client (other than by trust), this mode is typically used in:

* **Trusted Enclaves**: Where the infrastructure owner controls both the server and the edge.
* **Development**: Where the data scientist is testing on their own laptop.
* **Air-Gapped Nodes**: Where downloading external code packages is prohibited by firewall rules.