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

# Local Development

> Run your application locally against an installed Cloud Adapter using the connect command and your normal AWS tools.

Keep your application, debugger and tests on your laptop while Cloud Adapter runs in your development cloud account. `tensor9 adapt cloud connect` makes that installation available at a local endpoint. Your application continues to use its normal AWS SDK; Cloud Adapter handles the requests through its configured target-cloud services.

For example, a local application can call the AWS S3 API through Cloud Adapter and store its objects in Google Cloud Storage. The application runs locally, while the adapter and target resources run in your cloud project. Calls can create billable cloud resources.

For development entirely with emulators, see [High Fidelity Cloud Emulators](https://docs.tensor9.com/cloud-adapter-early-access/local-testing/overview.md).

## Prepare a development installation

[Install the CLI and authenticate](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/install-and-authenticate.md), then install Cloud Adapter in a dedicated development project or subscription. You need your target cloud's CLI and credentials, OpenTofu, Docker and kubectl. Connecting uses your Google Cloud or Azure identity to access the cluster and retrieve the installation's application credential.

The following example installs on Google Cloud. Choose your own project, region, zone and installation name:

```bash theme={null}
export GCP_PROJECT="my-development-project"

tensor9 adapt cloud install \
  --target gcp --projectId "$GCP_PROJECT" \
  --region us-west1 --zone us-west1-a \
  --name dev-adapter --dir "$HOME/tensor9/dev-adapter"
```

Review the resources and permissions printed by the installer before approving provisioning. If license approval is pending, complete that approval and resume the same installation. If Tensor9 has supplied a signed license file, add `--licenseFile /private/path/license.json`.

> [!NOTE]
>
> The customer CLI uses production by default. Keep the directory that the installer prints for connection and recovery.

For an existing Google Cloud or Azure installation, start with its completed installation directory. You can reuse that installation across development sessions. See [Full mode](https://docs.tensor9.com/cloud-adapter-early-access/deployment/provisioned.md) for the deployment model.

## What connect does

| Command | Behavior |
| - | - |
| `connect --dir DIR` | Prints the selected installation and connection instructions. It does not start a tunnel. |
| `connect --dir DIR --forward` | Opens a loopback tunnel to the installation's private Cloud Adapter endpoint and keeps running. |
| `connect --dir DIR --env` | Writes a private AWS profile and prints shell exports that select the profile, endpoint and signing region. |

The forward uses the installation's kubeconfig and `kubectl port-forward`. The local endpoint defaults to `http://127.0.0.1:65534`. For an installation with a TLS door, the connection command verifies the remote certificate while forwarding requests.

## Terminal 1: open the connection

First, inspect the instructions for your installation:

```bash theme={null}
tensor9 adapt cloud connect --dir "$HOME/tensor9/dev-adapter"
```

Then start the tunnel and leave this terminal running:

```bash theme={null}
tensor9 adapt cloud connect \
  --dir "$HOME/tensor9/dev-adapter" --forward
```

The tunnel exposes the installed adapter to your laptop. It does not install another adapter or run your application.

## Terminal 2: configure your development shell

In a separate terminal, load the connection settings and make an identity request:

```bash theme={null}
eval "$(tensor9 adapt cloud connect \
  --dir "$HOME/tensor9/dev-adapter" --env)"

aws sts get-caller-identity
```

The AWS CLI now sends this request to your Cloud Adapter. The returned account is the installation's AWS-facing account. Keep the first terminal running while using this shell.

The exports include `AWS_CONFIG_FILE`, `AWS_PROFILE`, `AWS_REGION`, `AWS_DEFAULT_REGION`, and `AWS_ENDPOINT_URL`. The profile uses AWS `credential_process` to retrieve the installation credential through your cloud identity; it does not print that credential. Your Tensor9 API key remains separate from the AWS-style application credential.

Use a dedicated development shell without pre-set AWS credentials or service-specific endpoint overrides. Those settings can override the generated profile or endpoint. Launch your application or IDE from this configured shell, or supply the same profile and endpoint settings in its run configuration.

## Run your application and tests

Keep your existing SDK calls and point their clients at the forwarded endpoint. For example, with the [AWS Python SDK](https://docs.tensor9.com/cloud-adapter-early-access/guides/aws-python-sdk.md):

```python theme={null}
import os
import boto3

session = boto3.Session(profile_name=os.environ["AWS_PROFILE"])
sts = session.client(
    "sts",
    endpoint_url=os.environ["AWS_ENDPOINT_URL"],
    region_name=os.environ["AWS_REGION"],
)

print(sts.get_caller_identity()["Account"])
```

Use the same client configuration pattern for the services your application needs. Configure the endpoint explicitly when an SDK does not read `AWS_ENDPOINT_URL`. See the [SDK guides](https://docs.tensor9.com/cloud-adapter-early-access/guides/index.md) for language-specific settings.

Run your normal application and test commands from this shell. Use unique test resource names and remove resources created by each test. Check the [service catalog](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/catalog.md) for the operations supported by your selected mapping. An STS identity response checks connectivity and signing; exercise your application's operations separately.

When a call fails, retain its request ID and [diagnostic response headers](https://docs.tensor9.com/cloud-adapter-early-access/debugging/response-headers.md). The [testing guide](https://docs.tensor9.com/cloud-adapter-early-access/local-testing/testing-your-adapters.md) covers resource read-back, failure cases and cleanup.

## Reconnect and switch installations

If the tunnel stops, restart `connect --forward` in the first terminal. You do not need to reinstall the adapter.

If port 65534 is busy, use another port on both commands:

```bash theme={null}
# Terminal 1
tensor9 adapt cloud connect \
  --dir "$HOME/tensor9/dev-adapter" --localPort 65533 --forward

# Terminal 2
eval "$(tensor9 adapt cloud connect \
  --dir "$HOME/tensor9/dev-adapter" --localPort 65533 --env)"
```

To switch installations, select the other installation directory, start its forward and load its settings in a new shell. Keep each application's endpoint, profile and signing region together.

| Symptom | Check |
| - | - |
| Connection refused at the local endpoint | Keep `connect --forward` running and use the same local port in both terminals. |
| kubectl cannot access the cluster | Check your signed-in `gcloud` or `az` identity and its access to the selected installation. |
| The AWS CLI cannot retrieve credentials | Check that your cloud identity can read the installation's Secret Manager or Key Vault credential. |
| Requests use another account or endpoint | Use a fresh development shell and remove conflicting AWS credential and endpoint settings before loading `connect --env`. |
| Connection works but an operation fails | Check the installed service mapping, application permissions and target-cloud response. |

## Finish a development session

Press Ctrl-C in the forwarding terminal and close the configured development shell. This stops local access while leaving the adapter and its cloud resources running for your next session. Cloud billing continues until those resources are removed.

When you no longer need the installation, review and run its uninstall command:

```bash theme={null}
tensor9 adapt cloud uninstall --dir "$HOME/tensor9/dev-adapter"
```

Keep its state directory until removal has completed. Uninstall removes the selected installation; it is not part of stopping your application's local development session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.