File I/O in TypeScript Golem Agents

Overview

Golem TypeScript agents run in a QuickJS-based WASM runtime that provides node:fs and node:fs/promises modules for filesystem operations. Use these to read files provisioned via the Initial File System (IFS) or to write temporary data.

To provision files into an agent's filesystem, load the golem-add-initial-files skill. To understand the full runtime environment, load the golem-js-runtime skill.

Reading Files

Synchronous

import * as fs from 'node:fs';

const content = fs.readFileSync('/data/config.json', 'utf-8');

Asynchronous

import * as fsp from 'node:fs/promises';

const content = await fsp.readFile('/data/config.json', 'utf-8');

Reading Binary Files

import * as fs from 'node:fs';

const buffer = fs.readFileSync('/data/image.png');
// buffer is a Buffer (Uint8Array subclass)

Writing Files

Only files provisioned with read-write permission (or files in non-provisioned paths) can be written to.

import * as fs from 'node:fs';

fs.writeFileSync('/tmp/output.txt', 'Hello, world!');

Asynchronous

import * as fsp from 'node:fs/promises';

await fsp.writeFile('/tmp/output.json', JSON.stringify(data));

Checking File Existence

import * as fs from 'node:fs';

if (fs.existsSync('/data/config.json')) {
  const content = fs.readFileSync('/data/config.json', 'utf-8');
}

Listing Directories

import * as fs from 'node:fs';

const files = fs.readdirSync('/data');
// files is string[]

Complete Agent Example

import { z } from 'zod';
import { defineAgent, method } from '@golemcloud/golem-ts-sdk';
import * as fs from 'node:fs';

export const FileReaderAgent = defineAgent({
  name: 'FileReaderAgent',
  id: { name: z.string() },
  methods: {
    readGreeting: method({ input: {}, returns: z.string() }),
    writeLog: method({ input: { message: z.string() }, returns: z.void() }),
  },
});

export const FileReaderAgentImpl = FileReaderAgent.implement({
  init: () => ({}),
  methods: {
    readGreeting() {
      const content = fs.readFileSync('/data/greeting.txt', 'utf-8');
      return content.trim();
    },
    writeLog({ message }) {
      fs.appendFileSync('/tmp/agent.log', message + '\n');
    },
  },
});

Key Constraints

• Use node:fs or node:fs/promises — they are fully supported in the QuickJS runtime
• Files provisioned via golem-add-initial-files with read-only permission cannot be written to
• The filesystem is per-agent-instance — each agent has its own isolated filesystem
• File changes within an agent are persistent across invocations (durable state)