Skip to main content

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 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.exec for running commands 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 { stdout, exitCode } = await d.exec(
    `grep -r ${JSON.stringify(event.query)} logs`,
  );

  return { statusCode: exitCode === 0 ? 200 : 404, body: stdout };
};
The disk.exec call runs grep inside an Archil-managed container with the filesystem mounted; only the result comes back to the Lambda. This is dramatically cheaper and faster than streaming the underlying log files through the function.

​
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 { stdout } = await d.exec(`grep -r ${JSON.stringify(event.query)} logs`);
  return { statusCode: 200, body: stdout };
};
  • 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).