Skip to main content
Every task runs its own code in an isolated cloud sandbox, separate from every other task. Files a worker reads or produces live in durable cloud storage first, so nothing is lost even if the sandbox itself goes away.

​
The sandbox

When a task needs to run code or work with files, CogniAgent starts a dedicated sandbox — an isolated cloud environment (built on e2b) that gives the worker a real filesystem and the ability to run commands. Think of it as a private computer that spins up just for that task.
  • One sandbox per task. Nothing another task does — even one bound to the same worker — is visible inside it.
  • Full-VM isolation. Each sandbox runs in its own microVM, so one task’s code can’t read or interfere with another’s.
  • Not always on. A sandbox costs compute time only while it’s active. CogniAgent pauses and resumes it automatically, so you’re not paying for idle time.
Simple file operations — reading a document, listing a folder — don’t need a sandbox at all. CogniAgent only spins one up when the worker actually needs to run code or a shell command, which keeps everyday turns fast and cheap.

​
S3 is the source of truth, not the sandbox

The most important thing to understand about task files: the sandbox is a cache, not the storage. Every file a task can see or produce is durably stored in cloud object storage (S3) first. The sandbox’s own disk is just a working copy that gets synced in when the task starts and synced back out whenever the task pauses. This design matters because cloud sandboxes are inherently ephemeral — they can be recycled, lost, or fail to resume cleanly. By treating the sandbox as disposable and the cloud storage as authoritative, a task’s files always survive even if its underlying sandbox doesn’t. Nothing about correctness depends on the sandbox itself preserving state between turns.
Because everything a task can see is scoped to that task’s own storage location, a worker’s files can never leak into another task by accident — the isolation lives in storage, not just compute.

​
Lifecycle: paused on idle, resumed on the next turn

A sandbox doesn’t run continuously for the life of a task — it follows the rhythm of the conversation:
1

Task starts

A sandbox is created and the task’s files sync in from cloud storage.
2

Turn runs

The worker reads, writes, and edits files, and can run code or commands, all inside the sandbox.
3

Idle

When there’s no activity, the sandbox automatically pauses. Before it does, any changed files are saved back to cloud storage first.
4

Next turn

When you send another message, the sandbox resumes in about a second, and picks up any files that changed elsewhere in the meantime.
5

Task ends

A final sync pushes any last changes to cloud storage before the sandbox is torn down.
This pause/resume cycle is what makes a task feel instant to pick back up, whether you reply a minute later or come back the next day, without leaving a sandbox (and its cost) running the whole time.

​
File tools

Inside a task, the worker uses file tools to read, write, and edit files directly on disk in the sandbox — the same files you can see in the task’s Files panel. As the worker produces new files (a report, a spreadsheet, a generated image), they show up in that panel live, mid-task, without waiting for the task to finish. Files a task works with generally fall into a few scopes:
  • Task files — private to this one task, the files the worker is actively producing or working on.
  • Worker files — files that belong to the worker itself, available across all of that worker’s tasks.
  • Shared workspace files — files available to every worker in the workspace.
Whichever scope a file belongs to, edits made through the file tools are the ones tracked and synced back to cloud storage — so a file you see appear in the panel is already durably saved, not just sitting in a temporary sandbox disk.
A worker can also pull files in from — and push files out to — connected apps and integrations (for example, an email attachment or a generated report), which land in the task’s files the same way. See Capabilities & connections for how those integrations are wired in as tools.

​
Retrieving output files

Anything a worker produces during a task — a document, an export, an analysis file — accumulates in that task’s Files panel as it’s created, and stays there for the life of the task. You can open, preview, or download those files directly from the panel at any point, including while the task is still running. Because the files are backed by durable cloud storage rather than the sandbox itself, they remain retrievable even after the task’s sandbox has paused or the task has finished.

​
Next steps

Tasks

Understand worker-bound vs. worker-less tasks and the task lifecycle.

Capabilities & connections

See how integrations bring files and actions into a task as tools.