Agent workspaces
Workspace sessions: one sealed VM, many commands
Our own account first
Short answer: A Smarty Pants workspace session keeps one sealed Linux VM open on a Mac so an agent can put files, run several commands and read results, then end it. Limits: 30 minutes per workspace, 10 minutes idle, 10 minutes per command, files up to 8 KB, 4 KB of output per stream. It runs on Smarty Pants' own account first and is not charged while tested. If the Mac's owner returns, it ends within 5 seconds.
A workspace session is the part of Smarty Pants agent workspaces that exists today. It keeps one sealed Linux VM open on an Apple Silicon Mac so your agent can write a file, run a program, run another one on the result, and read the answer back. When you end it, everything is gone. All details here come from the live agent docs.
Who can use sessions today?
Smarty Pants’ own account first. Sessions are not charged while Smarty Pants tests them, and other accounts cannot use them until they open. The agent docs will say when they do.
What are the limits?
Short and small: 30 minutes per workspace and files up to 8 KB.
| Limit | Value |
|---|---|
| Workspace lifetime | 30 minutes |
| Idle timeout | 10 minutes |
| Per command | Up to 10 minutes |
| File size | Up to 8 KB |
| Output | 4 KB per stream |
| Network | None |
| After it ends | Nothing is kept |
| Owner returns | Workspace ends within 5 seconds, OWNER_RETURNED |
| Charge | Not charged while tested |
The VM is the same kind used for CPU jobs: ARM64 Linux with Python 3, Node.js and a basic shell.
How do I use a session from Python?
With sp.workspace() in the starter kit. The VM stays open until the with block ends.
from smartypants import SmartyPants
sp = SmartyPants()
with sp.workspace(minutes=10) as ws: # one VM until the block ends
ws.put_file("notes.txt", "first line\n")
ws.run("sh", "echo second line >> notes.txt")
print(ws.run("python", "print(open('notes.txt').read().upper())")["stdout"])
print(ws.get_file("notes.txt"))
This example is copied from the live docs. It puts a file, adds to it with a shell command, reads it with Python, and fetches the file back, all in one VM.
Which API calls does a session use?
Five routes: create, run, move files, read a request, end.
| Call | What it does |
|---|---|
POST /v1/cpu/sessions |
Create a workspace (one VM) |
POST /v1/cpu/sessions/{id}/exec |
Run a command in it |
POST /v1/cpu/sessions/{id}/files |
Put or get a file |
GET /v1/cpu/sessions/{id}/requests/{requestId} |
Read the result of each request |
DELETE /v1/cpu/sessions/{id} |
End the workspace |
Each command or file call is a request with its own id; you read its outcome with the GET route. Always end a session with DELETE when you are done rather than waiting for the timeout.
What should my agent do when it sees OWNER_RETURNED?
Treat it as normal, not as a bug. The Mac’s owner comes first: if they return, the workspace ends within 5 seconds and the request says OWNER_RETURNED.
Good habits:
- Keep each command short and redoable.
- Fetch any file you need as soon as a step produces it.
- On
OWNER_RETURNED, start a new session, put the inputs back and redo the last step.
Continuing a workspace on another Mac is Planned and not available; see snapshots and recovery.
What should not go into a session?
Secrets and confidential data. The VM protects the Mac’s owner from your code. It does not keep your files or memory confidential from the Mac’s owner.
Use sessions for public code, test data and throwaway work. If you need internet access, large files or work that runs for hours, a hosted sandbox on dedicated servers fits better today.
What is available today and what is Planned?
| Feature | Status |
|---|---|
| Sessions on Smarty Pants’ own account, with the limits above | Available today |
| Sessions from your own account | Planned |
| Snapshots and recovery | Planned |
| Internet access from a workspace | Planned |
| Model calls from a workspace | Planned |
| Several sessions at once | Planned |
| CLI and SDK | Planned |
Planned features are not available. We’ll announce it on smartypants.network/docs/agents when each one opens.
Where next?
Read the workspaces overview for what is Planned, or CPU jobs for single 30-second runs. For background, see AI agent sandboxes explained.
Frequently asked questions
How long can a workspace session last?
Up to 30 minutes per workspace. It also ends after 10 minutes idle, and each command can run up to 10 minutes.
Are workspace sessions charged?
Not while Smarty Pants tests them on its own account. Other accounts cannot use them yet.
What does OWNER_RETURNED mean?
The Mac's owner came back, so the workspace ended within 5 seconds. Start a new session and redo the step that was interrupted.
Are files kept after a session ends?
No. Files live until the workspace ends and nothing is kept after. Fetch what you need before you end it.
Can a session install packages from the internet?
No. The VM has no network today. Internet access from a workspace is Planned and not available.