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

# AWS Lambda

> Use Archil disks from AWS Lambda functions

AWS Lambda functions are ephemeral -- they spin up, run your code, and disappear. Any data written to
`/tmp` is lost between invocations. Archil gives your Lambda functions persistent, shared storage backed
by S3 without managing EFS or writing directly to the S3 API.

Lambda doesn't support FUSE mounts, so the natural fit is the [`disk` SDK](/sdks/typescript) — it's pure
JavaScript, has no native dependencies, and gives you [`disk.grep`](/compute/search-files) for parallel
search and [`disk.exec`](/compute/serverless-execution) for arbitrary commands, both run directly against
the filesystem without pulling data through the Lambda.

## Install the SDK

Add `disk` to your Lambda project:

```bash theme={null}
npm install disk
```

## Lambda handler

This handler runs a command against an Archil disk and returns the result — no data is ever copied
through the Lambda:

```typescript theme={null}
import * as archil from "disk";

archil.configure({
  apiKey: process.env.ARCHIL_API_KEY,
  region: "aws-us-east-1",
});

export const handler = async (event: { diskId: string; query: string }) => {
  const d = await archil.getDisk(event.diskId);

  const { matches, stoppedReason } = await d.grep({
    directory: "logs",
    pattern: event.query,
    recursive: true,
  });

  return {
    statusCode: matches.length > 0 ? 200 : 404,
    body: JSON.stringify({ matches, stoppedReason }),
  };
};
```

The `disk.grep` call fans the search out across Archil-managed containers with the filesystem mounted;
only the matching lines come back to the Lambda. This is dramatically cheaper and faster than streaming
the underlying log files through the function, and it scales across many containers as `logs` grows
instead of being capped by a single one. For arbitrary commands beyond search, use
[`disk.exec`](/compute/serverless-execution) instead.

## IAM and credentials

`disk` calls the Archil control plane over HTTPS, which means it needs an API key. Set
`ARCHIL_API_KEY` (and optionally `ARCHIL_REGION`) on the Lambda function as an environment variable
or, better, pull it from AWS Secrets Manager during cold start.

The serverless `exec` containers themselves don't need any AWS credentials configured on the Lambda
side — they run inside Archil's infrastructure with the disk's own data-source credentials.

## Cold start considerations

`disk` is a thin HTTP client, so cold starts are dominated by the Lambda runtime itself rather than
SDK initialization. To minimize end-to-end latency:

* **Hoist `archil.configure` and `archil.getDisk` out of the handler** so warm invocations skip both:

```typescript theme={null}
import * as archil from "disk";

archil.configure({
  apiKey: process.env.ARCHIL_API_KEY,
  region: "aws-us-east-1",
});

const diskPromise = archil.getDisk(process.env.DISK_ID!);

export const handler = async (event: { query: string }) => {
  const d = await diskPromise;
  const { matches } = await d.grep({ directory: "logs", pattern: event.query, recursive: true });
  return { statusCode: 200, body: JSON.stringify(matches) };
};
```

* **Choose a Lambda region close to the disk's Archil region** to minimize round-trip latency on
  control-plane calls.
* **Increase Lambda memory** if cold starts are slow — Lambda allocates CPU proportionally to memory,
  and TLS setup is CPU-bound.

## Reading and writing files inside Lambda

If the Lambda needs to manipulate file contents directly (rather than dispatching work to the
filesystem), the simplest approach is still to do it through `disk.exec`:

```typescript theme={null}
const d = await archil.getDisk(diskId);

await d.exec(`echo ${JSON.stringify(JSON.stringify(event))} > /events/${Date.now()}.json`);

const { stdout } = await d.exec(`cat /config.json`);
```

For the rare case where you need a low-level filesystem client running *inside* the Lambda — for
example, to stream a large file's bytes through the Lambda — see the
[`@archildata/native` package](/sdks/typescript#low-level-protocol-access). It only ships binaries
for Linux x64 and arm64 (both Lambda architectures are supported).