# Workspace

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](/services).

## Before you start

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.

## Run a command

```text
In the workspace, clone github.com/acme/site and run its tests.
```

The client calls `stack_workspace_run`. From code or the terminal:

```typescript
const run = await stack.accounts.workspace.exec('acct_123', {
  command: 'git --version',
}, { passportToken });
// run.workspace.id, run.exit_code, run.output
```

```bash
npx @getstackrun/cli account workspace acct_123 run --command "git --version"
```

- Without workspace_id, the first command makes a workspace. Pass the id it returns to keep working in the same one.
- A command runs for 120 seconds unless timeout_seconds (--timeout) names another length. There is no longest.
- background: true (--background) answers at once with a command_id and lets the command run as long as it runs. It takes no timeout and no stack_access.
- stack_workspace_command reads a background command back by its command_id: its status (running, succeeded or failed), its exit code and the end of what it printed.
- Output is returned up to 64 KB.
- The machine has a shell, git and its own internet access.
- stack_access: true gives the command a short-lived Passport, so it can reach your connected services through STACK. It is off by default. Logins from the vault are never on the machine.

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.

## Read and write files

```typescript
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.

## Save a result to the drive

```typescript
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](/docs/account/drive).

## Pause, resume and delete

- An idle workspace is paused after 15 minutes. Its files stay.
- The next command or file call resumes it. There is no separate resume.
- A paused workspace is deleted after 7 days.
- stack_stop_workspace pauses one now, or deletes it with delete: true.
- stack_list_workspaces lists the workspaces the caller can use.

You can change the idle time, the days kept and how many workspaces an account may have:

```bash
npx @getstackrun/cli account workspace-settings set acct_123 --idle-pause 30 --delete-after 14 --max-workspaces 5
```

Settings 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`.

- The idle time is 5 minutes or more, or 0 for no idle pause.
- The days kept are 1 or more, or 0 to keep a paused workspace until you delete it. Its disk is charged for as long as it is kept.
- The number of workspaces is 1 or more. STACK sets no ceiling.

## Share a workspace between agents

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:

```bash
npx @getstackrun/cli account workspace-sharing acct_123 --workspace wsp_abc --off
```

## What counts as an action

A 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.

## When it is refused

- 409 WORKSPACE_LIMIT - the account has as many workspaces as it may. Delete one.
- 409 WORKSPACE_NOT_ACTIVE - the workspace is starting, pausing or being deleted. Try again shortly.
- 404 WORKSPACE_FILE_NOT_FOUND - no file at that path.
- 413 WORKSPACE_FILE_TOO_LARGE - the file passes the size limit of the call.
- 402 INSUFFICIENT_BALANCE - the credit cannot cover the start.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as workspace.exec, never with the text of the command, and as drive.upload for a save. A policy that caps how long a command may run refuses a background command.

## Reference

Every field is on [Workspace and Browser](/docs/api/account-workspace-browser). Every tool is in the [tool reference](/docs/mcp-tools).
