Local Development

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.

Prepare a development installation

Install the CLI and authenticate, 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:

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.

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 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:

tensor9 adapt cloud connect --dir "$HOME/tensor9/dev-adapter"

Then start the tunnel and leave this terminal running:

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:

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:

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 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 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. The testing guide 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:

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

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.

Tensor9 Cloud Adapter

How It Works

Getting Started

Configuration

Deployment

Costs

Support

Amazon Web Services

Google Cloud

Microsoft Azure

Making Trade-offs

Operations with Agents

Tuning

Debugging