Custom Tools

Custom Tools let you bring your organization’s internal tools onto Tamarind and use them everywhere the platform already goes: the web UI, the REST API, batch workflows, pipelines, and the Agent / MCP server. You develop the tool; Tamarind handles scaling, infrastructure, and sharing with your teammates. Manage your tools at app.tamarind.bio/app/custom-tools.

Overview

Each custom tool has four tabs:

Code — edit source files, view previously deployed versions, and inspect build logs.
Test — run any version of the tool against test inputs from the browser.
Config — manage the tool’s display metadata, compute settings, and input schema.
Settings — configure the GitHub integration and admin options.

Once deployed, a custom tool shows up alongside Tamarind’s built-in tools and can be invoked from the UI, the API, Batch, Pipelines, and the MCP server.

Versioning

Each tool is versioned with consecutive integers. Click any previously deployed version to load it in the code editor. Editing files and clicking Deploy builds a new version. Each version carries its own input schema, which you can edit from the Config tab. This means older versions remain runnable with the inputs they were deployed with, even if you change the schema later. If you save a new version without touching the Dockerfile or requirements files, the image is not rebuilt — only the source code is updated, so iteration is fast. Use Manage Visibility in the top right of the tool page to share a tool with members of your organization.

GitHub integration

You can connect a tool to a GitHub repository so that every push to a chosen branch creates a new tool version. Under the Settings tab you can:

Link or unlink a GitHub repository and branch.
Toggle automatic publishing — on means new versions go live immediately; off means an admin manually publishes each version.

The GitHub integration is installed as a GitHub App. You need admin access to the GitHub account or organization in order to install it. Organization admins manage the integration at app.tamarind.bio/org-settings?tab=github-integration. A working starter repo is available at github.com/Tamarind-Bio/tamarind-custom-tools-template — fork it as a starting point.

Build and runtime

Build. Images are built in AWS CodeBuild. You may base your image on any public Docker image. Your source code is not available during the build stage — it is mounted into the container at runtime — so your Dockerfile should install dependencies only and should not COPY application code. Runtime. Your tool runs inside a Linux Docker container. The runtime container has no internet access.

CUDA compatibility

Tamarind’s GPU hosts currently provide:

Host property	Current value
NVIDIA driver version	580.178.04
Maximum host-supported CUDA version / Driver API	13.0
Host architecture	Linux x86_64

Your application should use CUDA 13.0 or earlier. GPU tools provide their CUDA runtime through their Docker image, so the runtime in your image can be older than 13.0 and does not need to match the host’s maximum exactly. It must also be compatible with your GPU framework and other dependencies. Use nvidia-smi to inspect the GPU and host driver available to your container. For a PyTorch image, you can also inspect the CUDA version used to build PyTorch and confirm that PyTorch can access the GPU:

nvidia-smi
python -c "import torch; print(torch.version.cuda); print(torch.cuda.is_available())"

Available GPUs

Set gpuType in your config.json to one of the following. Use "None" for CPU-only tools.

`gpuType`	GPU
`None`	CPU only
`T4`	NVIDIA T4
`L4`	NVIDIA L4
`L40S`	NVIDIA L40S
`A10`	NVIDIA A10
`A100`	NVIDIA A100

Tool ID

Every tool has a tool ID, a fixed unique identifier used throughout the platform — including when invoking the tool through the API, batch, pipelines, or MCP. The tool ID is chosen when you create the tool from the UI and is immutable after creation.

Configuration (`config.json`)

A tool’s non-code settings live in a config.json file at the root of your repository. The same fields are editable in the Config tab of the UI. The schema is published at app.tamarind.bio/tamarind-tool.schema.json.

Top-level fields

Field	Type	Required	Description
`displayName`	string	yes	Human-readable tool name shown in the UI. Max 50 characters.
`description`	string	no	One-liner shown on the tool card.
`functions`	string[]	no	Long-description bullets — one string per bullet.
`gpuType`	enum	no	GPU type for the container. `"None"` for CPU-only. See Available GPUs.
`cpu`	integer	no	Number of CPU cores. Between 1 and 8.
`memory`	string	no	Memory allocation, e.g. `"12Gi"` or `"32Gi"`.
`envVars`	`object<string,string>`	no	Environment variables passed to the container at runtime. Keys must be `UPPER_SNAKE_CASE`.
`inputs`	Input[]	yes	User-facing input fields. Mirrors the Inputs section of the Config tab.

Do not put credentials (API keys, passwords, tokens) in envVars. Values are stored as plain environment variables, not encrypted secrets, and are visible to anyone with access to the tool’s config. The runtime container also has no internet access, so outbound credentials would not be usable anyway.

Inputs

Each entry in inputs describes one user-facing field. Every input supports these common fields:

Field	Type	Required	Description
`name`	string	yes	Programmatic name. Must match `^[A-Za-z][A-Za-z0-9_]*$`, so it starts with a letter; a leading underscore is reserved for internal settings. Used as the key in API calls.
`type`	string	yes	One of the input types below.
`displayName`	string	no	Label shown in the UI. Defaults to `name` if omitted.
`descr`	string	no	Help text shown under the field.
`required`	boolean	no	Whether the user must provide a value. Defaults to `false`.

The type field determines which additional fields are allowed:

file — arbitrary file upload

Accepts a file upload. You must specify the allowed extensions.

Field	Type	Required	Description
`extension`	string[]	yes	Allowed file extensions, lowercase, no dot. Example: `["csv", "tsv"]`.

{
  "name": "input_data",
  "type": "file",
  "displayName": "Input CSV",
  "extension": ["csv"],
  "required": true
}

pdb — protein structure

A .pdb file upload. Tamarind renders a structure preview in the UI automatically.

{
  "name": "target",
  "type": "pdb",
  "displayName": "Target structure",
  "required": true
}

sdf — small molecule

An .sdf file upload for small-molecule inputs.

{
  "name": "ligand",
  "type": "sdf",
  "required": true
}

sequence — protein sequence

A protein sequence string. Rendered as a sequence input in the UI.

Field	Type	Required	Description
`default`	string	no	Default sequence value.
`usesMsa`	boolean	no	Run Tamarind’s MSA server on this input before your tool. See Multiple sequence alignments.
`usesTemplates`	boolean	no	Also run a PDB100 template search on this input. Requires `usesMsa`. See Structure templates.

{
  "name": "sequence",
  "type": "sequence",
  "displayName": "Target sequence",
  "required": true
}

smiles — SMILES string

A SMILES string for a small molecule.

Field	Type	Required	Description
`default`	string	no	Default SMILES value.

{
  "name": "ligand_smiles",
  "type": "smiles",
  "default": "CCO"
}

text — free text

A single-line text input.

Field	Type	Required	Description
`default`	string	no	Default text value.

{
  "name": "job_label",
  "type": "text",
  "default": ""
}

number — numeric input

A numeric field with optional bounds.

Field	Type	Required	Description
`default`	number	no	Default numeric value.
`lowerBound`	number	no	Minimum allowed value.
`upperBound`	number	no	Maximum allowed value.

{
  "name": "num_samples",
  "type": "number",
  "default": 10,
  "lowerBound": 1,
  "upperBound": 100
}

boolean — checkbox

A true/false toggle.

Field	Type	Required	Description
`default`	boolean \| null	no	Default checked state. `null` means unset.

{
  "name": "use_relaxation",
  "type": "boolean",
  "default": false
}

A dropdown with a fixed list of string options.

Field	Type	Required	Description
`options`	string[]	yes	Available options. At least one required.
`default`	string	no	Default selected option.

{
  "name": "model_size",
  "type": "dropdown",
  "options": ["small", "medium", "large"],
  "default": "medium"
}

Multiple sequence alignments

Many structure and cofolding models need a multiple sequence alignment. Your container has no internet access at runtime, so it cannot query an MSA server itself. Instead, mark your sequence input with usesMsa and Tamarind runs its own MSA server before your tool starts, then delivers the results into the container as files.

"inputs": [
  { "name": "target_sequence", "type": "sequence", "usesMsa": true }
]

Name the input whatever suits your tool. The flag is what Tamarind keys on, not the name. Your tool receives one alignment per chain, numbered from 1:

inputs/msas/1.a3m
inputs/msas/2.a3m

Chains are the colon-separated parts of the sequence the user submits, so SEQ1:SEQ2 produces 1.a3m and 2.a3m, while a single-chain input produces just 1.a3m. Each file is an unpaired alignment for that chain in a3m format. If your model pairs chains across species, it does that itself from these files. Read the files defensively. If an alignment is unavailable for a chain, that file is absent rather than empty, and the job still runs; treat a missing msas/<n>.a3m as “this chain has no alignment” and fall back to the bare sequence.

usesMsa is only supported on an input of type sequence, because that is the field the MSA stage sends to the aligner, and at most one input per tool may set it. Running the alignment adds MSA time to the job’s cost.

Structure templates

If your model uses structural templates, Tamarind can run a PDB100 template search alongside the alignment and hand your container the results. This is the same template search our cofolding tools use, so your model sees the same reference set. Add usesTemplates to the input that already has usesMsa:

"inputs": [
  { "name": "target_sequence", "type": "sequence", "usesMsa": true, "usesTemplates": true }
]

Your tool receives the search hits, one file per chain, numbered the same way as the alignments:

inputs/templates/1.m8
inputs/templates/2.m8

and the matching structures, in mmCIF format:

inputs/templates/structures/1abc.cif
inputs/templates/structures/2xyz.cif

Each .m8 is an MMseqs2 BLAST-tab hits file whose target column is <pdbid>_<chain>. The structures are deduplicated across chains, so a template matching three chains appears once in structures/ while showing up in three .m8 files. That means the two directories have different file counts, by design: read the .m8 for which templates apply to which chain, and structures/ for the coordinates. Read both defensively, the same way as the alignments. If the search returns no hits, or the job predates this feature, the files are absent rather than empty and the job still runs. Treat a missing templates/ as “no templates for this job” and fall back to your template-free path.

usesTemplates requires usesMsa on the same input. The template search is an extra step on the same search the alignment runs, not a separate stage, so it cannot run on its own. Because it rides that search, it adds very little to the job’s cost beyond the alignment you are already paying for.

Example `config.json`

{
  "displayName": "My Binder Scorer",
  "description": "Scores candidate binders against a target structure.",
  "functions": [
    "Scores binder–target complexes with an internal model",
    "Returns per-residue confidence"
  ],
  "gpuType": "L40S",
  "cpu": 4,
  "memory": "32Gi",
  "envVars": {
    "MODEL_VERSION": "v3",
    "LOG_LEVEL": "INFO"
  },
  "inputs": [
    {
      "name": "target",
      "type": "pdb",
      "displayName": "Target structure",
      "required": true
    },
    {
      "name": "binder_sequence",
      "type": "sequence",
      "displayName": "Binder sequence",
      "required": true
    },
    {
      "name": "num_samples",
      "type": "number",
      "default": 10,
      "lowerBound": 1,
      "upperBound": 100
    }
  ]
}

Security

Images are built in isolated AWS CodeBuild jobs. Source code is only mounted at runtime, never baked into the image.
The runtime container has no internet access, so tools cannot exfiltrate inputs or reach external services.
Tools are private to your organization by default. Use Manage Visibility to control who can see and run them.

Running a custom tool via the API

Custom tools are submitted through the same /submit-job endpoint as built-in tools. Pass your tool ID as type, and put your configured input values under settings:

import requests

api_key = "***************"
headers = {'x-api-key': api_key}
base_url = "https://app.tamarind.bio/api/"

params = {
  "jobName": "myJobName",
  "type": "my-tool-id",
  "settings": {
    "input_field_1": "value",
    "input_field_2": "value"
  }
}
response = requests.post(base_url + "submit-job", headers=headers, json=params)
print(response.text)

The keys inside settings must match the name fields defined in your tool’s inputs schema. See the API reference for polling job status and retrieving results.

Tasks

Tools

Platform

Agent

Support

Overview

Versioning

GitHub integration

Build and runtime

CUDA compatibility

Available GPUs

Tool ID

Configuration (`config.json`)

Top-level fields

Inputs

Multiple sequence alignments

Structure templates

Example `config.json`

Security

Running a custom tool via the API

​Overview

​Versioning

​Sharing and visibility

​GitHub integration

​Build and runtime

​CUDA compatibility

​Available GPUs

​Tool ID

​Configuration (config.json)

​Top-level fields

​Inputs

​Multiple sequence alignments

​Structure templates

​Example config.json

​Security

​Running a custom tool via the API

Overview

Versioning

Sharing and visibility

GitHub integration

Build and runtime

CUDA compatibility

Available GPUs

Tool ID

Configuration (`config.json`)

Top-level fields

Inputs

Multiple sequence alignments

Structure templates

Example `config.json`

Security

Running a custom tool via the API