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

# sandbox

> cpln sandbox — Manage sandboxes and connect to running sandbox environments.

Manage sandboxes

```none theme={null}
cpln sandbox [SUBCOMMAND]
```

```text theme={null}
Commands:
  cpln sandbox connect <ref>  Connect to a running sandbox

Options:
  --help  Show help  [boolean]
```

***

#### sandbox connect

Connect to a running sandbox

**Usage**

```none theme={null}
cpln sandbox connect <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --ide   IDE or connection mode to launch.  [choices: "vscode", "cursor", "ssh", "browser", "terminal"] [default: "vscode"]
    --port  Preferred local SSH port. Defaults to an available port chosen automatically.  [number]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Connect to a running sandbox using the default IDE (VS Code)

  <CodeGroup>
    ```bash Command theme={null}
    cpln sandbox connect demo-sandbox --org demo-cpln-organization --gvc demo-cpln-gvc
    ```

    ```text Output theme={null}
    VS Code launched. Press Ctrl+C to stop the port-forward when done.
      Reconnect anytime with: code --remote ssh-remote+cpln-dev-demo-sandbox /workspace
    ```
  </CodeGroup>

  * Open an SSH tunnel to the sandbox and connect from any terminal or IDE

  <CodeGroup>
    ```bash Command theme={null}
    cpln sandbox connect demo-sandbox --ide ssh --org demo-cpln-organization --gvc demo-cpln-gvc
    ```

    ```text Output theme={null}
    SSH tunnel ready. Connect with "ssh cpln-dev-demo-sandbox", or use "cpln-dev-demo-sandbox" as a Remote-SSH host in your IDE.
      Press Ctrl+C to stop the port-forward when done.
    ```
  </CodeGroup>

  * Open an SSH tunnel using a preferred local port

  <CodeGroup>
    ```bash Command theme={null}
    cpln sandbox connect demo-sandbox --ide ssh --port 2222 --org demo-cpln-organization --gvc demo-cpln-gvc
    ```

    ```text Output theme={null}
    SSH tunnel ready. Connect with "ssh cpln-dev-demo-sandbox", or use "cpln-dev-demo-sandbox" as a Remote-SSH host in your IDE.
      Press Ctrl+C to stop the port-forward when done.
    ```
  </CodeGroup>

  * Open the sandbox IDE in the browser

  <CodeGroup>
    ```bash Command theme={null}
    cpln sandbox connect demo-sandbox --ide browser --org demo-cpln-organization --gvc demo-cpln-gvc
    ```

    ```text Output theme={null}
    Your sandbox password: <sandbox-password>
    If your browser did not open, visit: https://demo-sandbox-demo-cpln-gvc.cpln.app/_ide/
    ```
  </CodeGroup>
</Accordion>

***