Commands

instance

Deploy, control and connect to instances from your terminal.

The instance commands create, list, change, start, stop and delete instances, read their logs, and open terminals on them.

featherless-cloud instance <subcommand> [options]

Subcommands that act on one instance take its name or its ID.

Create an instance

featherless-cloud instance create --name dev --template featherless/rocm-pytorch --gpu-count 1
featherless-cloud instance create --name api --image ghcr.io/acme/api:3 --registry ghcr --gpu-count 2 --port 8000
featherless-cloud instance create --name prep --compute-type cpu --cpu-cores 8 --volume data:/workspace
OptionDescription
--name <name>Instance name. Random when omitted.
--template <name>Template to deploy: your template's name, org/<name> for one shared in your organization, featherless/<name> for an official one, or an ID. Add :<version> for an official template's older version. Other options override the template.
--template-id <id>Template to deploy, by ID.
--template-version <version>Version of an official template, such as 2.12.0. Newest by default.
--image <reference>Container image to run, or to replace the template's.
--registry <name|id>Registry credential for a private image.
--compute-type <gpu|cpu>GPU (default) or CPU compute.
--gpu-type <text>GPU model, matched on part of its name.
--gpu-count <n>GPUs: 1, 2, 4 or 8.
--cpu-cores <n>vCPUs, with --compute-type cpu.
--disk <gb>Container disk, 20–2,000. Default 20.
--volume <name>:<path>Mount a network volume. Repeatable.
--command <string>Start command, split on spaces, without shell quoting.
--env <K=V>Environment variable. Repeatable.
--secret <K=V>Secret variable, available as a file under $FEATHERLESS_SECRETS_PATH. Repeatable.
--port <port>Serve a port at a public HTTPS address. Repeatable.

List instances

featherless-cloud instance list
featherless-cloud instance list --page 2 --limit 50
OptionDescription
--page <n>Page number. Default 1.
--limit <n>Instances per page, 1–100. Default 20.

Show an instance

featherless-cloud instance get dev

Prints its status, compute, image, volumes, SSH command and public addresses.

Change an instance

featherless-cloud instance update dev --port 8000 --port 8888
featherless-cloud instance update dev --disk 200 --env HF_HOME=/workspace/hf
OptionDescription
--name <name>Rename the instance.
--image <reference>Container image.
--registry <name|id|null>Registry credential, or null to pull without one.
--disk <gb>Container disk, 20–2,000.
--command <string>Start command.
--env <K=V>Environment variable. Repeatable. Replaces the whole list.
--port <port|none>Public port. Repeatable. Replaces the whole list; none removes them all.

Port and name changes apply at once. Other changes restart a running instance, which erases its container disk.

Start, stop and restart

featherless-cloud instance start dev
featherless-cloud instance stop dev
featherless-cloud instance restart dev

Stopping and restarting erase the container disk. See Manage instances.

Delete an instance

featherless-cloud instance delete dev
featherless-cloud instance delete dev --yes
OptionDescription
--yesSkip the confirmation.

Read logs and history

featherless-cloud instance logs dev --follow
featherless-cloud instance logs dev --tail 2000
featherless-cloud instance history dev
OptionDescription
--tail <n>Recent lines to show, 1–5,000. Default 500.
--headShow the beginning of the output instead.
--followKeep printing new lines.

history lists lifecycle events such as starts, stops and failures.

Open a terminal

featherless-cloud instance shell dev
featherless-cloud instance ssh dev
featherless-cloud instance tmux dev
featherless-cloud instance tmux dev training
  • shell opens the browser terminal's shell, in the tmux session default. It needs no SSH key.
  • ssh connects with your OpenSSH client, SSH config and agent.
  • tmux attaches to the tmux session default, or to the named session, creating it if needed. Names have 1–64 letters, numbers, underscores or hyphens.
OptionDescription
-i, --identity <file>Private key for ssh and tmux. Otherwise your SSH config and agent apply.

ssh and tmux need your public key added with ssh-keys add. Detach from tmux with Ctrl-b d. Press Enter, then ~. to disconnect SSH.