# 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.

```bash
featherless-cloud instance <subcommand> [options]
```

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

## Create an instance

```bash
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
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

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

## List instances

```bash
featherless-cloud instance list
featherless-cloud instance list --page 2 --limit 50
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --page <n>
      </code>
    </td>
    
    <td>
      Page number. Default 1.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --limit <n>
      </code>
    </td>
    
    <td>
      Instances per page, 1–100. Default 20.
    </td>
  </tr>
</tbody>
</table>

## Show an instance

```bash
featherless-cloud instance get dev
```

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

## Change an instance

```bash
featherless-cloud instance update dev --port 8000 --port 8888
featherless-cloud instance update dev --disk 200 --env HF_HOME=/workspace/hf
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --name <name>
      </code>
    </td>
    
    <td>
      Rename the instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --image <reference>
      </code>
    </td>
    
    <td>
      Container image.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --registry <name|id|null>
      </code>
    </td>
    
    <td>
      Registry credential, or <code>
        null
      </code>
      
       to pull without one.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --disk <gb>
      </code>
    </td>
    
    <td>
      Container disk, 20–2,000.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --command <string>
      </code>
    </td>
    
    <td>
      Start command.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --env <K=V>
      </code>
    </td>
    
    <td>
      Environment variable. Repeatable. Replaces the whole list.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --port <port|none>
      </code>
    </td>
    
    <td>
      Public port. Repeatable. Replaces the whole list; <code>
        none
      </code>
      
       removes them all.
    </td>
  </tr>
</tbody>
</table>

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

## Start, stop and restart

```bash
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](/instances/manage).

## Delete an instance

```bash
featherless-cloud instance delete dev
featherless-cloud instance delete dev --yes
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --yes
      </code>
    </td>
    
    <td>
      Skip the confirmation.
    </td>
  </tr>
</tbody>
</table>

## Read logs and history

```bash
featherless-cloud instance logs dev --follow
featherless-cloud instance logs dev --tail 2000
featherless-cloud instance history dev
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --tail <n>
      </code>
    </td>
    
    <td>
      Recent lines to show, 1–5,000. Default 500.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --head
      </code>
    </td>
    
    <td>
      Show the beginning of the output instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --follow
      </code>
    </td>
    
    <td>
      Keep printing new lines.
    </td>
  </tr>
</tbody>
</table>

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

## Open a terminal

```bash
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.

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        -i
      </code>
      
      , <code>
        --identity <file>
      </code>
    </td>
    
    <td>
      Private key for <code>
        ssh
      </code>
      
       and <code>
        tmux
      </code>
      
      . Otherwise your SSH config and agent apply.
    </td>
  </tr>
</tbody>
</table>

`ssh` and `tmux` need your public key added with [`ssh-keys add`](/cli/ssh-keys). Detach from tmux with **Ctrl-b d**. Press Enter, then `~.` to disconnect SSH.
