Computers
Every bot works on its own sandboxed Linux computer: a shell, a home folder that persists between chats, a browser that stays signed in, and on desktop computers, a screen you can watch and control. Use this page to understand what's on a computer, how it sleeps and wakes, and how to step in when a bot needs a hand.
If you run your own server, provider setup (Docker, gVisor, E2B, Daytona) lives on Self-hosting computers.
Team, private and personal computers
| Kind | Who uses it | Shown in the app as |
|---|---|---|
| Team computer | Every bot in the workspace that has no computer of its own. One per workspace. | Team computer |
| Private computer | One bot. Its files stay separate from the team computer. | {bot}'s computer |
| Your own computer | Bots you allow, through the desktop app. See Your own computer. | This device |
A bot with no setting uses its private computer if it has one, otherwise the team computer. To pick a different one, open the bot's Bot profile → Computer and choose Automatic or a specific computer.
Workspace admins manage the team computer. Whoever manages a bot manages its private computer. Bots never share a computer across workspaces.
Create a private computer
- Open Settings → Advanced → Computers.
- Tap New computer.
- Choose the bot under For bot and give the computer a Name.
- Turn on With a desktop if you want a screen you can watch live. It uses more memory.
- Tap Create.
Each computer's card says what the machine is: whose it is, its system and size (for example Ubuntu 24.04 · 1 CPU · 1 GB RAM · 10 GB disk), a Saved pill when its files are kept while it's stopped, and when it was last used. From the same list, each computer's More menu offers Manage, Restart, Reset…, Live view (desktop computers), Switch to Desktop or Switch to Headless, Rename and Delete. Deleting a computer also deletes its files, snapshots and restore points. The team computer has no Delete option.
What's on a computer
Every computer starts from Casama's image, based on Ubuntu 24.04:
| Area | Included |
|---|---|
| Shell and tools | bash, git, curl, wget, jq, ripgrep, zip and unzip, nano, vim, OpenSSH client, ffmpeg, build tools |
| Languages | Node.js 24, Python 3 with pip and venv |
| Documents | LibreOffice, pandoc, Poppler, qpdf and Tesseract, for the PDF, Word, Excel and PowerPoint skills |
| Browser | Chromium, driven by the bot through agent-browser |
| Desktop computers only | A desktop with a taskbar (Browser, Terminal, Text editor), accessibility tooling so the bot can use apps, and the live view streamer |
The bot works as an unprivileged user named casama, and its home folder is the only place that persists. On the default Docker provider the rest of the filesystem is read-only, so install extra tools into the home folder: pip install installs for the user, and npm install -g installs under ~/.npm-global. /tmp is a 1 GB scratch space that's cleared when the computer sleeps.
By default, a computer on the Docker provider gets 1 CPU and 1 GB of memory. Your server's operator can change these defaults.
On Casama Cloud, your plan sets each computer's size and how many can run at once:
| Plan | Size of each computer | Running at once |
|---|---|---|
| Free | 1 CPU, 1 GB | 1 |
| Plus | 1 CPU, 1 GB | 1 |
| Pro | 2 CPUs, 2 GB | 2 |
| Max | 4 CPUs, 4 GB | 2 |
When you're at the limit and something needs another computer, Casama puts one that nobody has used for 2 minutes to sleep. If every running computer is in use, the new one doesn't start and the app offers a bigger plan. See Usage and plans. Self-hosted servers have no such limits.
Headless and desktop computers
New computers are Headless unless you turn on a desktop. A headless computer has a shell, files and a browser, but no screen. Its Screen tab shows the bot's open browser page, refreshed every 5 seconds, and stays blank until the bot opens a page.
A Desktop computer adds a real screen that you can watch and control live, and the bot can use desktop apps. On a desktop computer the bot's browser runs as a visible window, so when you take over you see exactly what the bot sees.
To switch, tap Switch to Desktop on the Screen tab, or use Switch to Desktop or Switch to Headless in the computer's More menu. A running computer restarts into the new profile, and its files are kept.
If a bot on a headless computer asks you to take over, for example to sign in, Casama switches that computer to the desktop profile for you and reopens the bot's current page in a visible window. The next time it sleeps after the takeover, it goes back to headless, since a desktop uses more memory. A desktop you chose yourself stays a desktop.
The computer panel
Open a bot's computer in any of these ways:
- In a chat on a wide screen, tap Show computer at the far right of the header. The panel opens beside the chat.
- In a chat on a phone or narrow window, open the More menu and tap Computer. While the bot is working on its computer, a computer button with a live dot also shows in the chat header.
- From Settings → Advanced → Computers, choose Manage in a computer's menu.
The panel shows the computer's name and state, with Sleep or Wake up, and four tabs: Screen, Terminal, Files and Manage. While the computer is on, the header shows small CPU, memory and disk meters; disk turns amber at 80% and red at 90%, and tapping a meter opens Manage.
On wide screens you can resize the side panel: drag its left edge. It stays between 360 px and 60% of the window, and the chat always keeps at least 420 px. Double-click the edge to reset it. The width is remembered on this device.
States you'll see
The state shown is checked against the sandbox each time the app lists computers, so a computer that says Running really is running. The panel refreshes itself while it's visible: every 3 seconds while the computer wakes, otherwise every 10 seconds, and again when you return to the app.
| State | Meaning |
|---|---|
| Setting up | The computer is being created for the first time. |
| Starting | It's waking up and restoring its files. |
| Running / Idle | It's awake and ready. |
| Going to sleep | Its files are being saved before it stops. |
| Asleep | Its files are saved and it isn't running. It wakes when needed. |
| Stopped | It's been stopped. |
| Error | Something went wrong. The panel shows the error, and Try again retries. |
Sleep and wake
A computer goes to sleep after 5 minutes with no bot working on it, no running commands and no one using it. Using it means typing or clicking in the terminal or live view while you're in the app; a live view or terminal left open in the background doesn't count. To pick a longer wait (15, 30 or 60 minutes) for one computer, set Goes to sleep after under Manage. A longer wait costs more. Sleeping saves the home folder (your files, the bot's workspace and its browser profile) to storage and stops the computer, so an asleep computer costs nothing to keep.
It wakes on its own the next time a bot needs it or you open the live view. You can also tap Wake up in the panel, or Sleep to put it to sleep now. Everything in the home folder comes back, including browser sign-ins.
Files
The Files tab browses the computer's home folder. You can open folders, go Up, Download a file, Upload files from your device, and Delete files. Files your bots make and files you upload both show up here.
Files you attach in a chat are uploaded to ~/workspace/uploads on the bot's computer. When a bot links a file it made, such as [report.md](workspace/report.md), tap the link to preview it and open, save or share it. See Chat.
The Terminal tab opens a shell on the same computer the bots use, so you can see and fix what they did. Tap Connect to start a session.
The browser and sign-ins
The bot's browser keeps its profile in the home folder, so cookies and sign-ins survive sleep, wake and restores. Sign in once, and the bot stays signed in.
When a site needs you, for example a password or a two-step code, the bot can ask you to take over. You sign in yourself in the live view, and nothing you type reaches the bot. See Take control.
Manage a computer
The Manage tab is where you fix a computer, see what it costs and holds, and set when it sleeps. Looking at it never wakes the computer or keeps it awake; some parts only fill in while it's on.
| Section | What it does |
|---|---|
| Not working right? | Fixes to try in order: Restart (about 20 seconds, nothing is lost), Reset system (a fresh system; ~/workspace stays) and Erase everything (like new). |
| Restore points | Saved copies of the home folder. Tap Restore on one, or Save a restore point now. |
| Storage | What fills the disk: your files, apps and tools, caches, the browser and other. Free up removes caches only, never your files, tools, settings or sign-ins. |
| Running now | Programs on the computer, busiest first. Stop ends one; the computer's own parts can't be stopped. |
| Goes to sleep after | 5, 15, 30 or 60 minutes without use. |
| This month | How long the computer was on, what it cost and a bar per day. |
| Used by | The bots that use this computer. |
| History | What happened, in sentences: woke up, went to sleep, restarted, reset, restore point saved, and who did it. |
| Download all files | A zip of ~/workspace, up to 1 GB. |
A reset saves a "Before reset" restore point first (on by default) and shows what's kept and what's removed. Erasing also asks you to type the computer's name. The reset runs in the background and shows its steps; when it's done, Undo puts everything back from that restore point. Only the people who manage the bot (or admins, for the team computer) can reset it.
When a computer breaks, the chat shows Restart and more fixes. A bot can also restart its own computer if it gets stuck.
Restore points
A restore point (also called a checkpoint) saves the computer's home folder so you can undo a change. The bot saves one automatically before commands that destroy data, such as rm -r or rm -f, git reset --hard, git clean -f, force pushes, package uninstalls, dd, mkfs and truncate -s 0. Bots can also save one on purpose before risky work.
To restore one:
- Open the computer panel and go to Manage.
- Under Restore points, tap Restore next to the one you want.
- Confirm. Files changed since then are replaced.
Checkpoints also appear in the chat and run timeline with a Restore button.
Each computer keeps its last 20 restore points or 7 days of them, whichever is fewer. Older ones are deleted.
Live view
Live view streams a desktop computer's screen to the app over WebRTC. Open it from the Screen tab (Open Live View, or Wake Up and Watch Live if it's asleep), from Live view in a computer's menu, or from a bot's request for help. Opening it wakes a sleeping computer.
The computer's screen comes first. A status chip in the header shows Live, Screenshots, Connecting… or Paused, with the latency while live; tap it for details. On wide screens the live view plays right inside the side panel. Tap Full screen to expand it and Back to the side panel to return. Turn a phone sideways for a bigger screen: the controls move into the black bars beside it.
If your network blocks live video, the view falls back to Screenshots, which update about once a second.
After 5 minutes without input, and with no bot working on the computer, the live view asks Still watching?. With no answer it shows Paused to save power, so the computer can sleep; Resume wakes it again. The stream also pauses while the app is in the background.
The dock
The controls sit in a dock at the bottom, in reach of your thumb. While you watch, it shows who has the screen and Take Control. While you're in control:
| Action | What it does |
|---|---|
| Keyboard | Opens your phone's keyboard. Enter types Return on the computer. Touch screens only. |
| Right-click on next tap | Makes your next tap a right-click. Touch screens only. |
| Paste | Sends your device's clipboard to the computer and presses Ctrl+V. |
| Copy | Presses Ctrl+C on the computer and puts the copied text on your device's clipboard. |
| Hand Back | Gives control back to the bot. |
More (⋯) holds Save Screenshot, and Teach a task while you're in control.
Take control and hand back
At any time you can take the mouse and keyboard from the bot.
- In the live view, tap Take Control. The status changes to You're in control.
- Do what you need to, such as signing in.
- Tap Hand Back. Optionally add a Note for the bot, for example "I signed in, carry on".
- Confirm with Hand Back.
While you're in control, the bot is paused. Its browser and desktop actions wait, and so do its shell and file commands. Nothing you type or see is sent to the bot. When you hand back, the bot reads your note and takes a fresh look at the screen before it continues.
Control returns to the bot on its own after 15 minutes without input from you. Only one person can be in control at a time. Others see Someone else is in control and can only watch.
When a bot asks for help
A bot can ask you to take over, for example at a sign-in page or a CAPTCHA. You get a notification, and the chat shows the request with Take Control. The live view shows "The bot asks: ..." with the reason. Take control and hand back as above, or tap Dismiss to decline. A request that no one answers expires after 24 hours.
Team computer folders
On a team computer, each bot works in its own folder, ~/workspace/bots/<name>, and ~/workspace/shared holds what the bots share. Both are created the first time the bot needs them.
- The folder name comes from the bot's name, such as
research-bot, with-2,-3and so on if two bots would clash. It's kept when you rename the bot, so its files don't move. - The bot's commands start in its own folder. Paths starting with
shared/orbots/point into the workspace, so every bot reaches the shared folder the same way. - This is a convention, not a wall. Bots on a team computer share one Linux user and can technically reach each other's folders. Give a bot a private computer when it needs real separation.
Desktop users at once
A team computer has one screen. Desktop users at once (1 to 10, default 1) limits how many bots use desktop tools at the same time. When the screen is in use, other bots keep working with the shell, files and browser. Admins change it from the team computer's More menu in Settings → Advanced → Computers.
Network and egress
On the default Docker provider, a computer has no direct route to the internet. All its traffic goes through Casama's egress proxy, which:
- Allows outbound HTTP and HTTPS to public addresses.
- Refuses private, loopback, link-local (including cloud metadata), CGNAT, multicast and reserved addresses. It checks the address it actually connects to, so DNS tricks can't get around it.
- Has no route for other traffic. SSH and other non-HTTP protocols can't reach the internet, so clone repositories over HTTPS.
- Applies per-computer connection and bandwidth rate limits.
Computers can't reach each other or Casama's internal services.
Use computers from the CLI
The CLI works with the team computer by default, or another one with --computer:
casama computer status # list computers and their state
casama computer start # wake (restore) the computer
casama computer stop # save files and sleep
casama computer shell # interactive terminal
casama computer files ls workspace # also get, put and rm
casama computer checkpoints # list undo points
casama computer restore <checkpoint-id>Limits
- The 10 GB disk size isn't enforced yet on the Docker provider.
- Restore points save the whole home folder each time rather than only what changed.
- Personal computers (your own, through the desktop app) have no Manage tab. See Your own computer.
- Bots work mostly from the screen's accessibility tree and page snapshots. Screenshots they take are saved as files, and models that read images also see the newest two in a run.
- On E2B and Daytona, computers have their own internet access, so the egress proxy's private-range blocking doesn't apply there.
- There's no setting in the app for per-workspace domain allow or deny lists.