---
title: Run scripts on Deephaven Enterprise workers
sidebar_label: Run scripts on workers
---

The `run_local_script` command runs a local Groovy or Python script on a remote Deephaven Enterprise worker. The tool sends the script body to the worker for evaluation. The tool creates a temporary Persistent Query for the worker and closes it when the script completes.

## Usage

```
/usr/illumon/latest/bin/run_local_script --script <path> [options] (--user <username> | --key-file <path> | --saml)
```

## Authentication

Exactly one authentication flag is required:

| Flag                       | Description                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| `-u` / `--user <username>` | Authenticate with a username. Prompts for a password.                                          |
| `-k` / `--key-file <path>` | Authenticate with a [private key file](../sys-admin/configuration/public-and-private-keys.md). |
| `-a` / `--saml`            | Authenticate using SAML.                                                                       |

## Options

| Flag                             | Description                                                                                                                       | Default                    |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `-s` / `--script <path>`         | Path to the local script to run. **Required.**                                                                                    | —                          |
| `-c` / `--connection-json <url>` | URL to the server's `connection.json` file.                                                                                       | Local server configuration |
| `-q` / `--query-server <name>`   | Name of the target query server.                                                                                                  | Controller selection       |
| `-m` / `--heap-size <GB>`        | JVM heap size in GB for the worker.                                                                                               | `4`                        |
| `-e` / `--worker-kind <kind>`    | Worker engine type. Use `DeephavenCommunity` for Core+ workers, or a custom `WorkerKind` configured by your system administrator. | `DeephavenCommunity`       |
| `-j` / `--jvm-arg <arg>`         | Additional JVM argument for the worker. May be repeated.                                                                          | —                          |
| `-t` / `--timeout <seconds>`     | Worker creation timeout in seconds.                                                                                               | `60`                       |
| `-l` / `--log-file <path>`       | File to write log messages from the worker.                                                                                       | `stdout`                   |

## Script language

The script language is inferred from the file extension. Files ending in `.groovy` run as Groovy; all other files run as Python.

## Examples

### Run a Python script

```bash
/usr/illumon/latest/bin/run_local_script \
    --script ./my_script.py \
    --key-file /etc/sysconfig/illumon.d/auth/priv-iris.base64.txt
```

### Run a Groovy script on a specific query server

```bash
/usr/illumon/latest/bin/run_local_script \
    --script ./my_script.groovy \
    --query-server query-server-1 \
    --key-file /etc/sysconfig/illumon.d/auth/priv-iris.base64.txt
```

### Connect to a remote server

Use `--connection-json` to specify a remote server:

```bash
/usr/illumon/latest/bin/run_local_script \
    --script ./my_script.py \
    --connection-json https://my-deephaven-server/iris/connection.json \
    --user my-username
```

### Increase heap size and pass JVM arguments

```bash
/usr/illumon/latest/bin/run_local_script \
    --script ./my_script.py \
    --heap-size 16 \
    --jvm-arg -Xss4m \
    --key-file /etc/sysconfig/illumon.d/auth/priv-iris.base64.txt
```

## Exit codes

The command exits with `0` on success and `1` if the script throws an exception or fails to execute.

## Related documentation

- [Merging data](../data-guide/merging.md) — Using `run_local_script` to run merge scripts
- [Public and private keys](../sys-admin/configuration/public-and-private-keys.md)