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. Because Lambda doesn’t support FUSE mounts, this guide uses the Archil TypeScript SDK to read and write files programmatically.

​
Install the SDK

Add the Archil packages to your Lambda project: 
npm install @archildata/client @archildata/just-bash
The native module ships pre-built binaries for Linux x64 and ARM64. Both Lambda architectures (x86_64 and arm64) are supported.

​
Lambda handler

This handler demonstrates reading and writing files on an Archil disk from a Lambda function: 
import { ArchilClient } from "@archildata/client";
import { ArchilFs } from "@archildata/just-bash";

export const handler = async (event: any) => {
  // Connect using IAM credentials from the Lambda execution role
  const client = await ArchilClient.connect({
    region: "aws-us-east-1",
    diskName: "myorg/mydisk",
  });
  const fs = await ArchilFs.create(client);

  try {
    // Write a result file
    const key = `results/${Date.now()}.json`;
    await fs.writeFile(`/${key}`, JSON.stringify(event));

    // Read it back
    const content = await fs.readFile(`/${key}`);

    return { statusCode: 200, body: content };
  } finally {
    // Always close to flush writes and release delegations
    await client.close();
  }
};

​
IAM configuration

Your Lambda execution role needs permission to authenticate with Archil. Add your Archil disk as an IAM disk user, then ensure your Lambda role has sts:GetCallerIdentity permission (included in most default policies). 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    }
  ]
}
Alternatively, set an ARCHIL_DISK_TOKEN environment variable on the Lambda function and the SDK will use token authentication automatically.

​
Cold start considerations

The SDK establishes a connection on each invocation. To minimize latency:
  • Reuse connections across warm invocations by creating the client outside the handler. Lambda keeps the module scope alive between invocations on the same container:
import { ArchilClient } from "@archildata/client";
import { ArchilFs } from "@archildata/just-bash";

let client: ArchilClient | null = null;
let fs: ArchilFs | null = null;

async function getFs() {
  if (!client) {
    client = await ArchilClient.connect({
      region: "aws-us-east-1",
      diskName: "myorg/mydisk",
    });
    fs = await ArchilFs.create(client);
  }
  return fs!;
}

export const handler = async (event: any) => {
  const fs = await getFs();
  const data = await fs.readFile("/config.json");
  return { statusCode: 200, body: data };
};
  • Choose a region close to your Lambda to reduce connection latency.
  • Increase Lambda memory if cold starts are slow — Lambda allocates CPU proportionally to memory.