Skip to main content
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 — it’s pure JavaScript, has no native dependencies, and gives you disk.grep for parallel search and disk.exec for arbitrary commands, both run directly against the filesystem without pulling data through the Lambda.

​
Install the SDK

Add disk to your Lambda project: 
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: 
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 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:
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: 
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. It only ships binaries for Linux x64 and arm64 (both Lambda architectures are supported).