Filesystem

Read and write files in the workspace filesystem. You can list directories, read/write individual files, check disk usage, and resize the writable storage.

List files

List the contents of a directory in the workspace.

const files = await ws.fs.list('ws_a1b2c3d4', { path: '/app' });

GET /workspace/:workspaceId/overlay?path=/app

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/overlay?path=/app" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Parameter	Type	Required	Description
`path`	`string`	No	Directory path to list. Default: `/`

Read file

Read the contents of a file.

const file = await ws.fs.read('ws_a1b2c3d4', { path: '/app/index.js' });

console.log(file); // File contents

GET /workspace/:workspaceId/overlay/files?path=/app/index.js

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/overlay/files?path=/app/index.js" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Parameter	Type	Required	Description
`path`	`string`	Yes	File path to read

Write file

Write content to a file. Creates parent directories if they don't exist.

await ws.fs.write('ws_a1b2c3d4', {
  path: '/app/server.js',
  content: Buffer.from(`
    const http = require('http');
    http.createServer((req, res) => {
      res.end('Hello!');
    }).listen(3000);
  `).toString('base64'),
});

POST /workspace/:workspaceId/overlay/files

{
  "path": "/app/server.js",
  "content": "Y29uc3QgaHR0cCA9IHJlcXVpcmUoJ2h0dHAnKTsK..."
}

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/overlay/files" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/app/server.js",
    "content": "Y29uc3QgaHR0cCA9IHJlcXVpcmUoJ2h0dHAnKTsK..."
  }'

Parameters

Parameter	Type	Required	Description
`path`	`string`	Yes	Destination file path
`content`	`string`	Yes	File content encoded as base64

Content must be base64-encoded. In Node.js: Buffer.from(text).toString('base64').

Disk usage

Get current disk usage for the workspace filesystem.

const usage = await ws.fs.usage('ws_a1b2c3d4');

GET /workspace/:workspaceId/overlay/usage

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/overlay/usage" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Resize

Resize the writable workspace filesystem. Subject to plan limits.

const result = await ws.fs.resize('ws_a1b2c3d4', { size_mb: 2048 });

console.log(result.wasRunning);   // true - VM was auto-stopped
console.log(result.relaunched);   // true - VM was auto-restarted

PUT /workspace/:workspaceId/overlay/resize

{
  "size_mb": 2048
}

curl -X PUT "https://api.oblien.com/workspace/ws_a1b2c3d4/overlay/resize" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "size_mb": 2048 }'

Parameters

Parameter	Type	Required	Description
`size_mb`	`number`	Yes	New size in MB (must be positive)

Behavior

Resize requires the VM to be stopped - the API will auto-stop a running VM, resize, and then auto-relaunch it
The new size is validated against your plan's disk limits
Response includes wasRunning and relaunched flags

Sync

Synchronize the workspace filesystem. Useful after batch file operations.

await ws.fs.sync('ws_a1b2c3d4');

POST /workspace/:workspaceId/overlay/sync

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/overlay/sync" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

On this page