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

# Serverless Framework and SAM Guide

> Evaluate serverless deployment tools against all cloud APIs they use, not only the function service.

Serverless Framework and AWS SAM are orchestration tools. Their normal deployment paths commonly use CloudFormation, S3, IAM, Lambda, API Gateway, logs, and sometimes ECR. A supported function or object-storage operation does not make the whole deployment path compatible.

## Start a local adapter

Start with one service mapping before evaluating a multi-service deployment. The bounded example uses S3 backed by Google Cloud Storage; replace it with the function or event mapping you intend to test only after checking its directed profile.

**1. Install or update the Tensor9 CLI**

Install the customer CLI with Homebrew, then confirm the binary is available:

```bash theme={null}
brew tap tensor9ine/tensor9
brew trust tensor9ine/tensor9
brew install tensor9
tensor9 --version
```

If `tensor9` is already installed, run `brew upgrade tensor9` instead of the install command.

**2. Authenticate with Tensor9**

To create a Tensor9 account and download an API key yourself, follow [Get a Tensor9 API key](https://docs.tensor9.com/byoc/getting-started/api-key.md).

A Tensor9 API key is required. Use the key issued during onboarding, or email [hello@tensor9.com](mailto:hello@tensor9.com) to request one for your organization. Do not share your account or key with another customer or organization.

If your secret manager has already supplied `T9_API_KEY`, skip the prompt. Otherwise, enter your key at a hidden prompt in the terminal where you will run `tensor9`:

> [tab] Bash
>
> ```bash theme={null}
> set +x
> IFS= read -r -s -p 'Tensor9 API key: ' T9_API_KEY
> printf '\n'
> export T9_API_KEY
> ```

> [tab] Zsh
>
> ```zsh theme={null}
> set +x
> IFS= read -r -s 'T9_API_KEY?Tensor9 API key: '
> printf '\n'
> export T9_API_KEY
> ```

Check that the variable is set without printing it, then verify your Tensor9 identity:

```bash theme={null}
: "${T9_API_KEY:?Set T9_API_KEY before continuing}"
tensor9 whoami
```

Confirm that the reported identity belongs to the intended customer account. Do not continue if authentication fails or the account is wrong. While `T9_API_KEY` is set, `tensor9` commands in this terminal use the key instead of any controller profile, so use a separate terminal for this work and run `unset T9_API_KEY` when you finish. Keep shell tracing disabled while using the key. Do not paste the key into commands, shell profiles, source files, screenshots or support messages.

See [Install and Authenticate](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/install-and-authenticate.md) for the planned license lifecycle, entitlements and credential boundaries.

**3. Inspect the S3 to Google Cloud Storage mapping**

Ask Tensor9 to describe the exact directed service mapping used by this guide:

```bash theme={null}
tensor9 explain \
  -origin aws::1.0.0::s3 \
  -target google::1.0.0::gcs \
  -fmt Human
```

Read the supported S3 operations and Google Cloud Storage limitations before starting the process. The mapping is directional: this command describes S3 requests adapted to Google Cloud Storage, not the reverse direction.

**4. Prepare Google Cloud access**

Authenticate with Google Cloud using its standard Application Default Credentials chain. The adapter uses that identity when it calls Google Cloud Storage.

Use a dedicated test project and narrowly scoped credentials. Do not put credentials in the command line, source code, or screenshots.

**5. Start the S3 service adapter**

Run the S3 to Google Cloud Storage adapter as a foreground process:

```bash theme={null}
tensor9 adapt svc run \
  --origin aws::1.0.0::s3 \
  --backend google::1.0.0::gcs
```

Leave this terminal open. This is the current foreground launcher, not the pending Docker launcher for [local development mode](https://docs.tensor9.com/cloud-adapter-early-access/deployment/single-binary.md). It calls your actual target-cloud services; it is separate from the in-memory emulator. Acquisition and license renewal require Tensor9 authentication. Keep the endpoint local to your test.

**6. Copy the listening endpoint**

When the command reports its listening endpoint, copy that exact value into a second terminal:

```bash theme={null}
export T9_CLOUD_ADAPTER_ENDPOINT="<endpoint printed by tensor9>"
```

Keep the endpoint local to the test unless you have deliberately configured network access and authentication for another machine.

**7. Run one bounded S3 request**

Continue with this page's client or tool instructions. Point only S3 at `T9_CLOUD_ADAPTER_ENDPOINT`, then perform one operation whose Google Cloud Storage effect you can verify independently.

Check both sides: read the S3-shaped response and inspect the native object or bucket in Google Cloud Storage. A successful client response alone does not prove that the target state is correct.

**8. Stop the local adapter**

Return to the first terminal and press **Control-C**. Confirm the process exits before deleting the test object or bucket with Google Cloud's native client.

If the request failed, preserve the request ID, adapter endpoint, S3 operation name, Google Cloud request ID, and any `x-t9-explain-*` receipt headers before stopping the process.

## Separate local and remote evidence

`sam build`, `sam local invoke`, package creation, and Serverless configuration validation can run locally. They are valuable application tests, but they do not prove that Cloud Adapter supports deployment, function management, or invocation in a target environment.

Record each phase separately:

| Phase | Typical dependencies |
| - | - |
| Build | Local runtime, package manager, container engine. |
| Package | Local files, S3 or ECR for remote assets. |
| Deploy | CloudFormation, IAM, Lambda, S3, API Gateway, logs. |
| Invoke and observe | Lambda, API Gateway, logs, metrics, tracing. |
| Remove | CloudFormation and every service owning retained resources. |

## Capture the real call graph

Pin the CLI and plugin versions, then run a disposable project with SDK/CLI debug logging in an isolated environment. Inventory every AWS service and operation. Check each against the service catalog and document any API the tool calls before it reaches the function resource.

Do not suppress denied or unsupported discovery calls simply to make the command continue. A skipped IAM, stack, or logs operation can produce a deployment that appears successful but cannot be operated or removed safely.

## Minimal compatibility fixture

Once the entire call graph is covered, use one small function with:

* no production data;
* one explicit runtime and handler;
* one simple invocation payload;
* no custom resources;
* no broad IAM policy;
* a unique stack and artifact prefix;
* a documented cleanup owner.

Test package upload, deployment status polling, invocation, logs or diagnostic response, configuration update, failed update, rollback, and removal. Verify the native target resources after every mutating phase.

## SAM-specific cautions

* `sam local` tests a local emulator path, not Cloud Adapter.
* Managed S3 packaging can introduce a bucket and endpoint you did not configure explicitly.
* Guided deployment stores answers for future runs; review the resulting configuration before reuse.
* Container-image functions add ECR operations and image-platform constraints.

## Serverless Framework cautions

* Plugins can add service calls that are absent from the base framework.
* Variable resolvers may call SSM, Secrets Manager, CloudFormation, or other APIs before deployment.
* Deployment buckets and pruning plugins can delete shared artifacts.
* Removal behavior depends on CloudFormation and target retention semantics.

## Choose a smaller first proof

If the full deployment path is not covered, test the supported API directly with an SDK or the [AWS CLI guide](https://docs.tensor9.com/cloud-adapter-early-access/guides/aws-cli.md). Treat local serverless tests as application evidence, not as Cloud Adapter compatibility evidence.

Use [Testing Your Adapters](https://docs.tensor9.com/cloud-adapter-early-access/local-testing/testing-your-adapters.md) to define the fixture and [Debugging Your Adapters](https://docs.tensor9.com/cloud-adapter-early-access/debugging/overview.md) to classify remote failures.


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