User-Defined Tools (Beta)

Starting with Galaxy 25.0, users can create their own tools without requiring administrator privileges to install them. These tools are written in YAML, defined through the Galaxy user interface, and stored in the database.

Differences from Standard Galaxy Tools

Standard Galaxy tools are written in XML and have broad access to the Galaxy database and filesystem during the command and configuration file templating phase, which uses the Cheetah templating language.

For example, the following XML tool command section queries the Galaxy database and writes a file to the home directory of the system user running the Galaxy process:

<command><![CDATA[
    #from pathlib import Path
    #user_id = $__app__.model.session().query($__app__.model.User.id).one()
    #open(f"{Path.home()}/a_file", "w").write("Hello!")
]]></command>

This level of access is acceptable when only administrators install tools. However, allowing regular users to define and execute arbitrary tools requires stricter controls.

To address this, Galaxy now supports a restricted tool language for user-defined tools. This format is modeled after the XML tool definition but replaces Cheetah templating with sandboxed JavaScript expressions that do not have access to the database or filesystem.

Example: Concatenate Files Tool (YAML)

class: GalaxyUserTool
id: cat_user_defined
version: "0.1"
name: Concatenate Files
description: tail-to-head
container: busybox
shell_command: |
  cat $(inputs.datasets.map((input) => input.path).join(' ')) > output.txt
inputs:
  - name: datasets
    multiple: true
    type: data
outputs:
  - name: output1
    type: data
    format_source: datasets
    from_work_dir: output.txt

Equivalent Tool in XML:

<tool id="cat" version="0.1">
    <description>tail-to-head</description>
    <requirements>
        <requirement type="container">busybox</requirement>
    </requirements>
    <command><![CDATA[
cat
#for dataset in datasets:
    '$dataset'
#end for
> '$output1'
    ]]></command>
    <inputs>
        <input name="datasets" format="data" type="data" multiple="true"/>
    </inputs>
    <outputs>
        <output name="output1" format_source="datasets" />
    </outputs>
</tool>

While the structure is similar, several key differences exist:

The YAML version includes a required class: GalaxyUserTool line to signal the use of the restricted UserToolSource schema.
All user-defined tools must be executed inside a container, specified using the container key.
The command to be executed is defined under the shell_command key, using a string with embedded JavaScript expressions inside $(). In the example above, the expression iterates over the input dataset paths and joins them into a single command string.

Enabling User-Defined Tools

To enable this feature:

Set enable_beta_tool_formats: true in your Galaxy configuration.
Create a role of type Custom Tool Execution in the admin user interdace.
Assign users or groups to this role.

Security considerations

User-defined tools share the same security risks as interactive tools.. See https://training.galaxyproject.org/training-material/topics/admin/tutorials/interactive-tools/tutorial.html#securing-interactive-tools for an extended discussion, and see https://github.com/galaxyproject/galaxy/blob/dev/test/integration/embedded_pulsar_job_conf.yml#L29 for a simple example that uses embedded pulsar to isolate mounts and disables network access. While the feature is in beta we recommend that only trusted users are allowed to use this feature.

Supported input parameter types

The YAML authoring layer exposes a deliberately narrow subset of Galaxy’s parameter model. The JSON schema published to the editor (ToolSourceSchema.json) is generated from this subset and rejects any unknown fields via extra="forbid", so unsupported attributes fail fast at parse time.

Supported leaf parameter types:

Type	Supported fields (beyond `name`, `label`, `help`, `optional`)
`boolean`	`value`
`integer`	`value`, `min`, `max`, `validators` (`in_range` only)
`float`	`value`, `min`, `max`, `validators` (`in_range` only)
`text`	`value`, `area`, `validators` (`length`, `regex`, `empty_field`)
`select`	`options` (static, non-empty), `multiple`, `validators` (`no_options`)
`color`	`value`
`data`	`format`, `multiple`, `min`, `max`
`data_collection`	`collection_type`, `format`

Supported structural groups: conditional, repeat, section. These recurse into the supported leaf set.

Example using several supported types:

class: GalaxyUserTool
id: example_tool
version: "0.1"
name: Example
container: busybox
shell_command: echo "$(inputs.greeting) $(inputs.count)"
inputs:
  - name: greeting
    type: select
    options:
      - { label: Hi, value: hi, selected: true }
      - { label: Hello, value: hello, selected: false }
  - name: count
    type: integer
    value: 1
    min: 1
    max: 10
  - name: extras
    type: repeat
    min: 0
    parameters:
      - name: input_file
        type: data
        format: txt
outputs: []

Types that exist in the XML tool vocabulary but are not supported in YAML user-defined tools and will be rejected at parse time: hidden, drill_down, data_column, genomebuild, group_tag, baseurl, rules, directory. XML-only fields such as truevalue, falsevalue, argument, is_dynamic, hidden (as a field), and parameter_type are likewise rejected on any parameter.

Limitations

The user-defined tool language is still evolving, and additional safety audits are ongoing.

Current limitations include:

Access to reference data is not supported
Access to metadata and metadata files (such as BAM indexes) is not supported
Access to the extra_files directory is not supported