Skip to main content
The Mesa SDK integrates with Vercel’s just-bash library to provide shell execution against Mesa repositories without needing a sandbox. This page covers the API surface exposed through @mesadev/sdk. For a higher-level overview, see the MesaFS just-bash guide.

​
Imports

The SDK re-exports the core just-bash types alongside the Mesa filesystem: 
import { Mesa, Bash, MesaFS } from "@mesadev/sdk";
import type {
  BashOptions,
  ExecResult,
  BashLogger,
  CommandName,
  CustomCommand,
  NetworkConfig,
  JavaScriptConfig,
  SecureFetch,
} from "@mesadev/sdk";

​
Creating a Filesystem

Use mesa.fs.create() to create a MesaFileSystem instance scoped to specific repositories: 
const mesa = new Mesa({ adminApiKey: process.env.MESA_ADMIN_API_KEY });

const fs = await mesa.fs.create({
  repos: [
    { name: "my-repo", desiredBookmark: "main" },
    { name: "another-repo", desiredBookmark: "feature-branch" },
  ],
  mode: "rw",
  cache: {
    diskCache: {
      path: "/tmp/mesa-cache",
      maxSizeBytes: 1024 * 1024 * 1024,
    },
  },
});

​
MesaFileSystemConfig

FieldTypeDescription
repos{ name: string; desiredBookmark: string }[]Repositories and bookmarks to mount
mode"ro" | "rw"Read-only or read-write access
cacheobjectOptional caching configuration
cache.diskCache.pathstringPath for on-disk cache
cache.diskCache.maxSizeBytesnumberMaximum cache size in bytes

​
Getting a Bash Shell

Call .bash() on a MesaFileSystem to get a Bash instance: 
const bash = fs.bash({
  env: { NODE_ENV: "production", CI: "true" },
  cwd: "/my-repo",
});

​
MesaBashOptions

OptionTypeDescription
envRecord<string, string>Environment variables for the shell
cwdstringInitial working directory
executionLimitsobjectResource limits (timeouts, memory)
fetchtypeof fetchCustom fetch for network access
networkNetworkConfigNetwork access configuration
pythonobjectPython runtime configuration
javascriptJavaScriptConfigJavaScript runtime configuration
commandsCommandName[]Built-in commands to enable
customCommandsCustomCommand[]User-defined commands
loggerBashLoggerLogging interface
Options like fs and files from BashOptions are intentionally omitted — the filesystem is always the MesaFileSystem instance, and files are populated from your Mesa repositories.
If you need to use advanced just-bash features such as overlay filesystems, you should separately install the just-bash package and use the MesaFileSystem instance directly to construct a Bash instance.
import { Mesa } from "@mesadev/sdk";
import { Bash } from "just-bash";

const mesa = new Mesa();
const fs = await mesa.fs.create({...});
const bash = new Bash({ fs, ...otherOptions });

​
Executing Commands

​
bash.exec(command)

Runs a shell command and returns the result. 
const result = await bash.exec("ls -la /my-repo/src");

​
ExecResult

FieldTypeDescription
stdoutstringStandard output
stderrstringStandard error
exitCodenumberExit code (0 = success)
const result = await bash.exec("grep -r 'TODO' /my-repo/src");

if (result.exitCode === 0) {
  console.log("Found TODOs:", result.stdout);
} else {
  console.log("No matches or error:", result.stderr);
}

​
IFileSystem Methods

The MesaFileSystem class implements the full IFileSystem interface from just-bash. All methods are async unless noted.

​
Reading

MethodReturnsDescription
readFile(path, options?)stringRead file with encoding
readFileBuffer(path)BufferRead file as raw bytes
readdir(path)string[]List directory entry names
readdirWithFileTypes(path)DirEntry[]List directory with type info
readlink(path)stringRead symlink target

​
Writing

MethodReturnsDescription
writeFile(path, content, options?)voidWrite string or bytes
appendFile(path, content, options?)voidAppend to file
mkdir(path, options?)voidCreate directory

​
Querying

MethodReturnsDescription
exists(path)booleanCheck file existence
stat(path)MetadataFile metadata (follows symlinks)
lstat(path)MetadataFile metadata (no symlink follow)
realpath(path)stringResolve canonical path
resolvePath(base, path)stringPure path resolution (sync)

​
Modifying

MethodReturnsDescription
rm(path, options?)voidRemove file or directory
cp(src, dest, options?)voidCopy file or directory
mv(src, dest)voidMove or rename
chmod(path, mode)voidChange permissions
utimes(path, atime, mtime)voidSet timestamps
symlink(target, linkPath)voidCreate symbolic link
link(existing, new)—Always returns ENOTSUP