Manage remote photons

The anatomy of a photon covered the creation and execution of photons. In this section, we will cover common commandline operations to manage remote photons and their deployments, including:

In the cloud, we have the definition of a "workspace", which holds photons and deployments. You can think of a workspace as a project, and photons as the building blocks of the project. Deployments are created from photons, and they are the actual running instances of the project. In the following, we will use the CLI to manage photons and deployments in a workspace.

We assume that you have already logged into your workspace. If not, refer to the quickstart for login instructions. We'll also assume that we have created a local photon, like

lep photon create -n myphoton -m hf:gpt2

We will use this photon to demonstrate the commands.

Push a photon to a workspace

Use lep photon push to push a photon to a workspace. This will upload the photon to the cloud and make it available for deployment.

lep photon push -n myphoton

List all photons

You can list all photons in your workspace with lep photon list:

lep photon list

Optionally, use --pattern to filter out the photons you want to see.

Photons created via lep photon create are always stored locally. To view the local photons, use lep photon list --local.

Remove a photon

Use lep photon remove to remove a photon from your workspace. Note that photons pushed to the workspace are versioned, and you can remove a specific version of a photon by specifying its version id. If only name is specified, the most recently pushed version is removed. If you want to remove all versions of a photon, use --all flag.

lep photon remove -n myphoton --all

Also, if you are removing a local photon, use lep photon remove --local.

If you are following along the commands in this section, before moving to the next, run lep photon push -n myphoton again to push the photon back to the workspace.

Run a photon

Use lep photon run to run a photon and create a deployment. In the easiest case, you can simply specify the name of the photon to run. This will create a deployment with the same name (if not existing) as the photon:

lep photon run -n myphoton

In default, created deployments are protected by the access token of the workspace. You can specify a different token with --token flag. If you want to create a public deployment, use --public flag. Public deployments are useful when you want to create a public API or a web app.

You can also specify a lot of other configurations for the deployment, such as the number of replicas, the resource shape, etc. For a full list of options, use lep photon run --help, or refer to the API reference.

List all deployments

Use lep deployment list to list all deployments in your workspace. You can also use --pattern to filter out the deployments you want to see.

lep deployment list

Inspect a deployment

Use lep deployment status to inspect the status a deployment. This will show you the details of the deployment, including the replicas, tokens, etc.:

lep deployment status -n myphoton

Further, use lep deployment log to view the logs of a deployment. This is useful when you want to debug a deployment:

lep deployment log -n myphoton

The log command will keep streaming the logs until you press Ctrl+C.

Remove a deployment

Use lep deployment remove to remove (aka, stop) a deployment:

lep deployment remove -n myphoton


The above lists commonly used commands to manage photons and deployments. For a complete list of CLI commands, refer to the API reference.