Skip to main content

OpenCloning Cloning API

This python packages contains an API that provides a series of entry points for in silico cloning. The API documentation can be accessed here.

You can also install it and use some of the exported functions, in particular for primer design.

Migrating between model versions and fixing model bugs

  • The data model changes, so the json files you created may not be compatible with the newest version of the library, which uses the latest data mode. You can easily fix this using python -m opencloning_linkml.migrations.migrate file.json see full documentation.
  • Before version 0.3, there was a bug for assembly fields that included locations spanning the origin. See the details and how to fix it in the documentation of this file.

Getting started

If you want to quickly set up a local instance of the frontend and backend of the application, check getting started in 5 minutes in the main repository.

For the configuration of the container via env variables, check the docker-compose file in the main repository.

Running locally

You can install this as a python package:

# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/bin/activate
# Install the package from pypi
pip install opencloning
# Run the API (uvicorn should be installed in the virtual environment)
uvicorn opencloning.main:app

Installing from GitHub (monorepo)

This repository is a uv workspace; the installable package lives in packages/opencloning/. When installing directly from GitHub, include the subdirectory fragment:

# uv
uv add "opencloning @ git+https://github.com/OpenCloning/OpenCloning_backend.git@master#subdirectory=packages/opencloning"

# pip
pip install "git+https://github.com/OpenCloning/OpenCloning_backend.git@master#subdirectory=packages/opencloning"

Running locally if you want to contribute

This repository is a uv workspace: the installable package lives under packages/opencloning/, and the repo root holds workspace metadata and shared dev dependencies. Install uv, then from the repository root:

# Install the workspace (editable opencloning + dev/test dependency groups) into .venv
uv sync

# Install the pre-commit hooks
uv run pre-commit install

# Run tools via uv, or activate .venv and use them directly
source .venv/bin/activate   # optional

The virtual environment is created at the repository root (.venv). For VS Code settings see the folder .vscode.

Now you should be able to run the api by running:

# The --reload argument will reload the API if you make changes to the code
uvicorn opencloning.main:app --reload --reload-exclude='.venv'

Then you should be able to open the API docs at http://127.0.0.1:8000/docs to know that your API is working.

Running locally with docker 🐳

If you want to serve the full site (backend and frontend) with docker, check getting started in 5 minutes in the main repository.

If you want to serve only the backend from a docker container, an image is available at manulera/opencloningbackend. The image is built from docker/opencloning.Dockerfile (repository root as build context) and exposes the port 3000. To run it:

docker build -f docker/opencloning.Dockerfile -t manulera/opencloningbackend .
docker run -d --name backendcontainer -p 8000:8000 manulera/opencloningbackend

To run with a read-only root filesystem while still allowing temporary files (required for tools like mafft), mount /tmp as tmpfs (RAM-backed writable storage).

docker run -d --name backendcontainer -p 8000:8000 \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=256M \
  manulera/opencloningbackend

If you want to build the test image locally, you can do so by:

docker build -f docker/opencloning.Dockerfile -t manulera/opencloningbackend-test --target builder-test .

If you don't want to download the repository and build the image, you can fetch the latest image from dockerhub.

docker pull manulera/opencloningbackend
docker run -d --name backendcontainer -p 8000:8000 manulera/opencloningbackend

The api will be running at http://localhost:8000, so you should be able to access the docs at http://localhost:8000/docs.

Connecting to the frontend

If you want to receive requests from the frontend, or from another web application you may have to include the url of the frontend application in the CORS exceptions. By default, if you run the dev server with uvicorn opencloning.main:app --reload --reload-exclude='.venv', the backend will accept requests coming from http://localhost:3000, which is the default address of the frontend dev server (ran with yarn start).

If you want to change the allowed origins, you can do so via env variables (comma-separated). e.g.:

ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 uvicorn opencloning.main:app --reload --reload-exclude='.venv'

Similarly, the frontend should be configured to send requests to the backend address, see here.

Serving the frontend from the backend

You may prefer to handle everything from a single server. You can do so by:

  • Build the frontend with yarn build.
  • Copy the folder build from the frontend to the root directory of the backend, and rename it to frontend.
  • Set the environment variable SERVE_FRONTEND=1 when running the backend. By default this will remove all allowed origins, but you can still set them with ALLOWED_ORIGINS.
  • Set the value of backendUrl in frontend/config.js to /.
  • Now, when you go to the root of the backend (e.g. http://localhost:8000), you should receive the frontend instead of the greeting page of the API.

You can see how this is done in this docker image and docker-compose file.

Running the tests locally

From the repository root (after uv sync):

This will require setting the ADDGENE_TOKEN environment variable, see Addgene authenticated access for more details.

uv run pytest packages/opencloning/tests -v -ks

If you wanted to run them in docker:

export COMPOSE_PROJECT_NAME=opencloning-local-docker
# Plus env vars for ADDGENE and NCBI API keys

docker compose \
  -f docker/docker-compose.postgres.yml \
  -f docker/docker-compose.ci-tests.yml \
  run --rm tests \
  python -m pytest -vs -o cache_dir=/tmp/pytest-cache

Addgene authenticated access

Addgene sequences are retrieved through the Addgene Developers API, which requires an API token with the catalog:retrieve-with-sequences scope. Request one from Addgene, and set it as an environment variable to enable Addgene imports:

export ADDGENE_TOKEN="your_addgene_api_token"

For one-off local runs you can also prefix commands:

ADDGENE_TOKEN="your_addgene_api_token" uv run pytest packages/opencloning/tests -v -ks

If the variable is not set, Addgene import endpoints return an informative error explaining that a token is required.

Genbank files are downloaded from https://api.developers.addgene.org/download/genbank/{sequence_id}/, which redirects to a presigned storage URL. Both hosts are in the default ALLOWED_EXTERNAL_URLS; if you override that variable, include them.

Use of the Addgene API and data must comply with Addgene Terms of Use.

For CI, configure a repository secret named ADDGENE_TOKEN so Addgene-dependent tests can run.

Catalogs

Catalogs are used to map ids to urls for several plasmid collections. They are stored under packages/opencloning/src/opencloning/catalogs/.

To update the catalogs, run the following command from the repository root:

uv run python scripts/update_catalogs.py

Metadata

Release files for opencloning 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opencloning 2.1.0
File Size Uploaded Provenance Actions
opencloning-2.1.0.tar.gz 1.1 MB With provenance Details for opencloning-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opencloning 2.1.0
File Interpreter ABI Platform Actions
opencloning-2.1.0-py3-none-any.whl Python 3 none any Details for opencloning-2.1.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / opencloning-2.1.0.tar.gz

Download URL opencloning-2.1.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
bb902b0ebac6b3c2f02570ab791511979e4be593a25093a9a14a07879485063f
BLAKE2b-256 checksum
How to use checksums
a4297bb07c7eb7b2b6029c0c9e2eccbb26ea1f9b47fd08c69e6bb5223d42dea4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / opencloning-2.1.0-py3-none-any.whl

Download URL opencloning-2.1.0-py3-none-any.whl
Size 171.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0cd847747eafc80b70d7ce3d503d4c6fddd1130149174378ecb128211d50a4ea
BLAKE2b-256 checksum
How to use checksums
29126cc8ce684e00e6439978690e0d2a8a63b19af5939b8999d3d2445626424e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for opencloning 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for opencloning-2.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page