← All documentation

Build

AI tools: inside and outside the sandbox

AI agents can read files, run commands and write code. Where you run one decides what it can reach, so choose on purpose.

An AI agent such as Claude Code is not just a chat window. It reads your files, runs commands and changes code, with your rights. On AOS you choose between two places to run one, and the difference is large.

Inside the sandbox: Claude Desktop

Claude (anthropic/claude) is in Software’s Third-party section. It is Anthropic’s Claude Desktop for Linux, and it runs in a sandbox set up for development:

It sees Detail
Its own folder ~/AppData/anthropic.claude
~/Projects Read and write: your code
~/.gitconfig Read-only, so commits carry your name
~/.claude and ~/.claude.json Claude Code’s sign-in and settings, shared with the Terminal and VS Code
Developer tools Everything installed through apm (cargo, node, gh, git…), read-only, plus podman and KVM
The network Outgoing only

It does not see your other files, your SSH keys, ~/.config, other apps’ data or browser profiles. It cannot reach the admin service, so it has no route to root, and it can’t push to git over SSH.

Logins are stored in the system’s keyring, separately for each app.

Outside the sandbox: an agent in the Terminal

You can also run the Claude Code CLI, or any other AI CLI, in the Terminal. Install it with Node.js (apm install the third-party nodejs/node, then npm install -g @anthropic-ai/claude-code) or with Anthropic’s own installer. Either way it ends up in ~/.local/bin. It then runs as you, with nothing in between:

  • It sees your whole home: SSH and GPG keys, every app’s data, browser profiles, password exports, everything.
  • It can run any command you can, including git push with your keys.
  • It can change your shell’s startup files and leave programs behind in ~/.local/bin.
  • If you unlocked admin within the last 15 minutes, it could use aos-root too: install packages, or change Wi-Fi and VPN settings.

Side by side

Sandboxed (Claude Desktop) Terminal (CLI)
Your files Its folder, ~/Projects, what you allow Everything in your home
SSH keys and git push No Yes
Installed tools Yes, read-only Yes
Admin actions Never If admin is unlocked
Network Outgoing Outgoing
Can leave things behind Only in its folders Anywhere in your home
Can open more on request You allow a folder in Software —

Which to use

  • Default to the sandbox. For coding in ~/Projects, Claude Desktop with Claude Code gives the agent your code and your tools and nothing else. If a prompt goes wrong, or the agent reads a malicious file, the damage is limited to what it could see.
  • Use the Terminal when the agent truly needs your environment: pushing over SSH, working outside ~/Projects, or system work. Then:
    • Don’t unlock admin while the agent runs. If you just did, wait 15 minutes, since the unlock lasts that long after the last admin action.
    • Keep secrets out of reach. Better still, run agents from a second, non-admin account (Settings → Users). It can’t use aos-root at all, and your own home stays encrypted and closed to it.
    • Review what it changed before you commit or push.
  • Need a folder outside ~/Projects? Grant it in Software → Claude → Permissions → Allow a folder… rather than switching to the Terminal.

Editors with AI built in

VS Code, VSCodium and Zed run sandboxed like Claude Desktop: ~/Projects, your installed tools and the shared ~/.claude sign-in. VS Code also has the SSH permission, so it can push. Claude Code’s extension signs in once and works in all of them.

Editors with a workspace

An editor can ask for a workspace instead of a plain sandbox. When you open a folder in it, its tools (the built-in terminal, the compiler, the language server, an AI agent) each start in a sandbox of their own, set up around that folder:

In a workspace Detail
The folder you opened Read and write: the only place real changes land
The rest of your home Readable, so dotfiles, gh and the Claude sign-in work. Anything written there goes to a private layer that belongs to the workspace and is never seen outside it
Each toolchain’s own folder Read and write, so cargo and npm caches are shared
SSH Through the agent only, and only if the editor has the SSH permission. The keys themselves stay hidden
Other apps’ data, ~/.gnupg, the keyrings Hidden
The network The editor’s own

So a build script, a test, an extension or an agent can’t change your shell’s start files, another project or another app’s data, however it goes wrong. A Claude Code setting, hook or memory written inside a workspace stays inside it, too. The one file shared both ways is the Claude sign-in itself, so a renewed login isn’t lost.

What a workspace can’t stop: it reads your home and has the network, so a hostile tool could send away what it reads. And whatever it writes into the project, a build script or a git hook, runs later wherever you run that project. Review before you build someone else’s code.

Software shows the workspace permission on the app’s page before you install it.

Local models

There is no package for local model runners (ollama, llama.cpp) yet. They can run in a podman container in the meantime.