How an agent runs commands and keeps files on its own Linux machine, moves results to the drive, and how you set when the machine pauses and when it is deleted. What the workspace is and what it costs is on Services.
The agent needs an open account whose workspace is ready, and its Passport. The account needs credit: each start holds the cost of its longest run and gives back what was not used.
In the workspace, clone github.com/acme/site and run its tests.The client calls stack_workspace_run. From code or the terminal:
const run = await stack.accounts.workspace.exec('acct_123', {
command: 'git --version',
}, { passportToken });
// run.workspace.id, run.exit_code, run.outputnpx @getstackrun/cli account workspace acct_123 run --command "git --version"What a command prints and what a file holds is content from outside. It is scanned, and with controls on flagged output is withheld from the agent.
const ws = stack.accounts.workspace;
await ws.writeFile('acct_123', run.workspace.id,
{ path: 'notes/todo.md', content_text: '- ship it' }, { passportToken });
const file = await ws.readFile('acct_123', run.workspace.id,
{ path: 'notes/todo.md' }, { passportToken });The tools are stack_workspace_read_file and stack_workspace_write_file. Each takes a file of at most 1 MB.
await ws.saveFile('acct_123', run.workspace.id, { path: 'out/report.pdf' }, { passportToken });The tool is stack_workspace_save_file. The file lands on the agent's drive, where it can be shared or attached to an email. For a larger file, make a drive upload link and send the file to it from the workspace with curl -T: see Drive and share links.
You can change the idle time, the days kept and how many workspaces an account may have:
npx @getstackrun/cli account workspace-settings set acct_123 --idle-pause 30 --delete-after 14 --max-workspaces 5Settings are the owner's or an admin's. Leave the account id out to set the default for every account. The tool is stack_set_workspace_settings.
A workspace is open to your other agents by default. Another agent runs commands in it with the owning account's id and its own Passport. Only the account's own agent makes or stops it. To keep one private:
npx @getstackrun/cli account workspace-sharing acct_123 --workspace wsp_abc --offA command, reading a background command, a file read, a file write and a save are one action each. Listing, stopping, sharing and settings are free. Machine time is charged from credit while it runs, after the hours the plan includes, and a paused workspace is charged for its disk only.
Every field is on Workspace and Browser. Every tool is in the tool reference.