> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# instances add

> Create a new instance under an existing app

<Note>
  This command is marked as unstable and may change in future releases.
</Note>

## Command: `phala instances add`

### Syntax

```
phala instances add [options]
```

### Description

Create a new instance under an existing app

### Options

| Option                                   | Description                                                 |
| ---------------------------------------- | ----------------------------------------------------------- |
| `--app-id <value>`                       | App ID (hex identifier). Defaults to app\_id in phala.toml. |
| `--node-id <value>, --teepod-id <value>` | Target node ID for the new instance.                        |
| `-c, --compose-file <value>`             | Path to Docker Compose file.                                |
| `--pre-launch-script <value>`            | Path to pre-launch script file.                             |
| `-e, --env-file <value>`                 | Path to environment file.                                   |
| `--compose-hash <value>`                 | Compose hash to use (existing revision).                    |

### Advanced Options

| Option                       | Description                                                                                                                                   |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--private-key <value>`      | Private key for signing on-chain transactions (or set PRIVATE\_KEY env var)                                                                   |
| `--rpc-url <value>`          | RPC URL for on-chain KMS transactions (or set ETH\_RPC\_URL env var)                                                                          |
| `--prepare-only`             | Prepare the instance and generate a commit token. Skips all on-chain operations.                                                              |
| `--commit`                   | Commit a previously prepared instance using a commit token. Requires --token, --compose-hash, and --transaction-hash.                         |
| `--token <value>`            | Commit token from a prepare-only request.                                                                                                     |
| `--transaction-hash <value>` | Transaction hash proving on-chain compose hash registration. Pass `already-registered` to skip the proof and rely on state-only verification. |

### Global Options

| Option                               | Description                                               |
| ------------------------------------ | --------------------------------------------------------- |
| `-h, --help`                         | Show help information for the current command             |
| `-v, --version`                      | Show CLI version                                          |
| `--api-token TOKEN, --api-key TOKEN` | API token for authenticating with Phala Cloud             |
| `-j, --json, --no-json`              | Output in JSON format                                     |
| `-i, --interactive`                  | Enable interactive mode                                   |
| `--cvm-id <value>`                   | CVM identifier (UUID, app\_id, instance\_id, or name)     |
| `--profile PROFILE`                  | Temporarily use a different auth profile for this command |
| `--api-version <value>`              | API version to use (e.g. 2025-10-28, 2026-01-21)          |

### Examples

* Add instance with existing compose

```bash theme={"system"}
phala instances add --app-id <app-id> --node-id 5
```

* Add instance with new Docker Compose

```bash theme={"system"}
phala instances add --app-id <app-id> --node-id 5 --compose-file docker-compose.yml
```

* Prepare for multisig approval

```bash theme={"system"}
phala instances add --app-id <app-id> --node-id 5 --compose-file docker-compose.yml --prepare-only
```

* Commit a prepared instance

```bash theme={"system"}
phala instances add --app-id <app-id> --commit --token <token> --compose-hash <hash> --transaction-hash <tx-hash>
```