Docs· lifo.sh

Services: tools that run on Lifo's servers

View as Markdown

A box is small on purpose. It doesn't carry a native ffmpeg, a GPU or a browser engine, and some jobs are too heavy for a tab anyway. For those, the command stays the same and the work happens on Lifo services: the files the command reads are uploaded, the tool runs in an isolated container, and what it writes comes back into the box.

Preview. Services are in development. The commands below work against a local service today; lifo.sh turns them on when the hosted one launches. Until then they say services "aren't available yet".

bash
lifo login
ffmpeg -i talk.mov -vf scale=1280:-2 -c:v libx264 talk.mp4
#   ffmpeg will run on Lifo Cloud; 1 file (48.2 MB) from this box is uploaded: talk.mov.
#   Allow? [o]nce / [a]lways for your account / [n]o: o
#   ... ffmpeg's own output ...
#   ☁ ffmpeg ran on Lifo Cloud: uploaded 1 file (48.2 MB), 21.40 s CPU, 1 file back
ls            # talk.mov  talk.mp4

It is real, native ffmpeg (version 7), not a WebAssembly build: every codec, and many times faster.

Why some tools are services and others run in the box, and the stand-in each service has in a tab: Where the line is.

The tools

CommandWhat runs
ffmpegnative ffmpeg 7
ffprobenative ffprobe 7
browsera real Chromium (headless, 149), one per box: see Browser

lifo services lists the job tools with their limits. More one-shot tools will follow the same way; GPU models are planned as sessions, like the browser.

Browser

browser drives a real Chromium for the box: page JavaScript runs, single-page apps work, and it has the same verbs as the text browser and Firefox (open, state, click, type, text, links, eval, screenshot, key, back, ...). It's attached on first use, with nothing to set up:

bash
browser open news.ycombinator.com && browser state
browser click new
browser text | head
browser info        # backend: Chromium on Lifo's Browser service (box "my-api")
  • Where it comes from. In a cloud box, BROWSER_WS_ENDPOINT points at the box's own browser (ws://browser.lifo.internal/cdp/<box>). Under lifo-sh or in any box with a login, browser asks the Browser service for one. In a browser tab the stand-ins answer (the text browser, or Firefox where the page has it) unless LIFO_BROWSER=remote. LIFO_BROWSER=local never uses the service.

  • It's the box's. Each box gets its own browser context: its own tabs, cookies and storage, which no other box (yours or anyone's) can see. Tabs stay open between commands and close by themselves after 5 idle minutes, or when a cloud box goes to sleep.

  • Bring your own tools. It's plain CDP, so playwright-core and puppeteer connect to the same endpoint, in a cloud box too:

    js
    import { chromium } from 'playwright-core';
    const browser = await chromium.connectOverCDP(process.env.BROWSER_WS_ENDPOINT);
    const page = browser.contexts()[0].pages()[0] ?? (await browser.contexts()[0].newPage());

    Outside a cloud box, get an endpoint from code: (await LifoServices.connect({ token })).browserSession('my-box') returns { wsEndpoint, screencastUrl } (the URL is good for 5 minutes to connect).

  • Any CDP endpoint. Set BROWSER_WS_ENDPOINT to your own Chromium's WebSocket (chrome --remote-debugging-port) and browser drives that instead.

  • Network. Pages reach the public internet only: loopback, private ranges and cloud metadata addresses are refused, and so are file:// and chrome:// URLs. Nothing leaves your box but the URLs you open (no files are uploaded), so browser doesn't ask first.

  • Limits (preview): browsers for 3 boxes at once per account, 8 tabs per box, sessions up to 60 minutes (reconnect for more), and one Chromium per account capped at 1 GB.

Your files, and asking first

Lifo runs in your browser so your files stay with you. A service is the exception, so it is never silent:

  • What is sent: the command's arguments, and the files it names that exist in the box (its inputs). Nothing else from the box. An output file that already exists isn't sent.

  • It asks the first time, per tool: once (this run), always (your account, in every box), or no.

  • Scripts and agents can't answer a prompt, so the command stops and says how to allow it:

    bash
    lifo services allow ffmpeg            # this box
    lifo services allow ffmpeg --always   # your account
    LIFO_SERVICES_ALLOW=ffmpeg ffmpeg ... # one run (or "all")
    lifo services deny ffmpeg             # ask again
  • On the server: each job runs in its own container with no network and nothing mounted but its own files, which are deleted when it ends. Inputs and results are kept for a day, per account, so a second run doesn't upload the same file again and you can fetch a result; then they're deleted. No other account can read them.

Where a command runs

LIFO_EXEC chooses:

auto (default)in the box when the box has its own version of the tool and the input is small; otherwise the service
localonly in the box. The command fails rather than upload anything
remotealways the service

A box gets its own version of a tool from a package, lifo install ffmpeg (ffmpeg.wasm: slower and fewer codecs, but nothing leaves the box; inputs up to 25 MB then stay local), or from your code:

js
import { Sandbox, setLocalTool } from '@lifo-sh/core';

const box = await Sandbox.create();
setLocalTool(box.kernel.vfs, 'ffmpeg', {
  maxBytes: 10 * 1024 * 1024,           // bigger inputs go to the service
  command: async (ctx) => { /* run ffmpeg.wasm with ctx.args, ctx.vfs */ return 0; },
});

How paths work

The job sees a folder that mirrors your working directory: in.wav and out/tone.mp3 mean the same there. Files elsewhere in the box (/data/a.mov, ../b.mov) work too; they're mapped in and their results mapped back. Two limits:

  • A path written inside another argument (a filter such as movie=logo.png) isn't seen, so that file isn't uploaded. Keep such files next to the command and name them as arguments where the tool allows it.
  • Network inputs (-i https://...) are refused: jobs have no network. Download with curl first.

Pipes carry text. ffprobe ... | jq works. Binary data through a pipe (ffmpeg ... -f mp3 - > out.mp3) doesn't survive a box's shell; write to a file instead.

Limits during the preview

  • 120 s per job, 1 CPU, 1 GB of memory.
  • 200 MB of input and 200 MB of output per job; 2 jobs at once.
  • A job that goes over is stopped and the command says why (exit code 124 for time, 137 for memory or size).

lifo services usage shows this month's jobs, CPU time and transfer. Nothing is billed during the preview.

From code

js
import { LifoServices } from '@lifo-sh/core';

const services = await LifoServices.connect({ token: 'lifo_...' });   // an API key from the dashboard
const result = await services.run({
  tool: 'ffmpeg',
  args: ['-i', 'in.wav', '-b:a', '64k', 'out.mp3'],
  files: [{ path: 'in.wav', bytes: wavBytes }],
  onStderr: (bytes) => process.stderr.write(bytes),
});
// { exitCode: 0, files: [{ path: 'out.mp3', sha256, size }], usage: { cpuMs, wallMs, ... }, uploaded }
const mp3 = await services.download(result.files[0].sha256);

run uploads only the files the service doesn't already have (by SHA-256), and signal (an AbortSignal) cancels the job.

The API

HTTP with a lifo_ key as a bearer token. Its address comes from the account server's /api/cli/config (servicesUrl), or LIFO_SERVICES_URL.

GET /v1/tools{ tools: [{ name, version, description, limits }], consent: { tools } }
GET /v1/consent, PUT /v1/consent{ tools } this account always allows
POST /v1/blobs/check{ hashes } returns { missing }
PUT /v1/blobs/:sha256upload one file
GET /v1/blobs/:sha256download a result
POST /v1/jobs{ tool, args, files: [{ path, sha256 }], dirs?, stdin?: { sha256 }, version? }; the response streams one JSON event per line: start, o/e (base64 stdout/stderr), file, exit
DELETE /v1/jobs/:idcancel
GET /v1/usage{ from, to, totals, tools }
POST /v1/browser/sessions{ box, state?: { cookies } } returns { box, wsEndpoint, screencastUrl, expiresAt, version, limits }
GET /v1/browser/sessionsthe account's Chromium and its boxes' browsers
GET / PUT /v1/browser/sessions/:box/statethe box browser's cookies, to save and restore
DELETE /v1/browser/sessions/:boxclose the box's browser
WS /v1/browser/cdp/:tokenCDP (the wsEndpoint)
WS /v1/browser/screencast/:tokenJPEG frames out, mouse, keys and navigation in
GET /v1/browser/usagethe browser's share of this month's usage

Edit this page on GitHub