Skip to main content

The sandbox

Every agent that runs on the OtoDock server runs inside a strict sandbox — a kernel-level isolation boundary that controls what files it can touch and what network it can reach. It's always on, with no opt-out, and it's the primary security boundary on the platform.

What the sandbox does​

When an agent runs, OtoDock wraps it in an isolated environment built fresh for that session:

  • Files outside its scope don't exist. The agent's view of the filesystem contains only the folders it's allowed to see — its own workspace, its knowledge, and (for managers) its configuration. Everything else on the server is simply absent from the agent's view — there's nothing to discover.
  • It can't see other processes. The agent runs in its own process space and can't observe or interfere with the OtoDock server or any other agent.
  • It has no special privileges. The agent runs without elevated system permissions.

This applies to everything an agent does — including any commands it runs in a shell and any tools it launches. There's nowhere to escape to, because the boundary is enforced by the operating system kernel — not by application rules that clever prompting might work around.

Network isolation​

The sandbox is also network-isolated, and this is one of its most important properties. By default, an agent on the server:

  • Can reach the public internet (to read documentation, call public APIs, etc.).
  • Cannot reach your internal network — not your other servers, not your home lab, not even other machines on the same subnet. Private network ranges are blocked at the kernel level.

This means an agent can't scan or probe your network, whether through its tools or through a raw shell command — and that's the default for every agent, with nothing to configure.

Granting access to a specific service​

When a tool legitimately needs to reach one internal service — say a metrics server or a home automation hub — you grant access to exactly that endpoint with a per-tool toggle. OtoDock opens a precise path to that one host and nothing else; every other host on your network stays unreachable.

→ Full walkthrough: Local network access.

What each agent can see​

The sandbox mounts a different set of folders depending on the agent's mode and the role of the person using it — matching the permission rules described in Permissions. In short:

  • An agent always works in its own folder tree — never another agent's.
  • A person's private space is visible only to them.
  • Configuration (the agent's persona and wiring) is visible only to managers.
  • Read access is broad enough for collaborators to understand the agent's state; the ability to change things is what role boundaries protect.

Beyond its folders, an agent sees the system's own toolchain — anything installed system-wide on the OtoDock host (or baked into the container image). Tools installed in a user's home directory aren't visible, and the agent's home is a throwaway temporary folder cleared when the session ends — so to give agents an extra CLI, install it system-wide.

Why there's no "unsandboxed" mode on the server​

Server-side agents are always sandboxed — there's deliberately no way to run one with full access to the host. No setting, no exception, no per-agent escape hatch: the boundary holds for every agent, every time, and that's exactly what makes it a boundary you can rely on.

If you review the compose file

You'll notice the server container relaxes a few Docker profiles (seccomp, apparmor, systempaths) and maps /dev/net/tun. These are what let the sandbox build its unprivileged isolation inside the container — the container itself stays non-root with no added capabilities, a smaller privilege footprint than the usual privileged-container approach. Don't remove them: without them, agents can't start.

Next steps​