> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> A reusable execution package — tools, knowledge, variables and a sandbox — that several agents and assistants share.

An **Environment** is everything an agent needs to *run*, packaged once and connected to as many agents and assistants as you like.

Without it, each agent carries its own copy of the same setup: the same MCPs, the same documents, the same API keys, the same terminal configuration. Change something and you change it in ten places, or in nine and forget the tenth.

![Environments](https://mintcdn.com/devic/DKyKkxiOLW4okLYC/images/environments/list.png?fit=max\&auto=format\&n=DKyKkxiOLW4okLYC\&q=85\&s=95df22fa7f1dac451eebd90a046c7444)

***

## What an environment carries

> [card] Tools
>
> The MCPs and tool groups every connected entity gets.

> [card] Knowledge
>
> Documents and folders the connected agents can read.

> [card] Environment variables
>
> Values available at runtime, encrypted at rest and shown masked.

> [card] Sandbox
>
> A real Linux machine: runtime, init script, installed CLIs and its snapshot.

***

## From the API and the CLI

Environments are not a dashboard-only feature. The whole lifecycle — create one
with its variables and init script, bake a snapshot, connect an agent, then
start a machine and run commands on it — is reachable from
[the API](https://docs.devic.ai/api-reference/endpoint/post-api-v1-environments.md) and the CLI:

```bash theme={null}
devic environments create --name "Reporting box" --runtime python3.13 \
  --env "DATABASE_URL=postgres://..." --init-script-file ./provision.sh --snapshots
devic environments snapshot init "Reporting box"
devic agents create --name "Reporter" --environment "Reporting box" --cron "0 7 * * 1-5"

devic sandbox start "Reporting box"
devic sandbox exec "Reporting box" 'cd /workspace && ./report.sh'
devic sandbox stop "Reporting box"
```

That last group is the practical way to verify an init script or a snapshot
before an agent depends on it: the machine you drive by hand is the same one
the agent gets.

> [!NOTE]
>
> These endpoints are not reachable with a tenant session token. They hand out a
> root shell, the account's secrets and the snapshot every tenant boots from —
> confining an end user to their own data is no answer to that. Use an API key.

***

## How connecting works

An agent or assistant connects to **one** environment; an environment serves many. The connection is **additive**: what the environment brings is added to what the entity already had, so connecting one never takes tools or documents away.

The connection itself can carry variables of its own, for values that differ per agent while everything else is shared. Precedence runs from most specific to least: **connection → environment → sandbox**.

> [!WARNING]
>
> The sandbox is the exception to "additive". When an environment with a sandbox is connected, **the environment governs the sandbox completely** — the entity's own terminal configuration is ignored at runtime, not merged. The interface makes it read-only and says so, because a setting that looks editable but has no effect is worse than one that is visibly locked.

***

## When to use one

| Situation | Environment? |
| - | - |
| Several agents work on the same systems with the same credentials | **Yes.** One place to rotate a key. |
| A team of agents shares a codebase or a working directory | **Yes.** They share a sandbox snapshot. |
| A single assistant with two documents and no tools | Not worth it. |
| Agents that must not see each other's credentials | Separate environments. |

***

## Next steps

> [card] [Configuration](https://docs.devic.ai/devic/environments/configuration.md)
>
> Variables, secrets, tools and knowledge.

> [card] [Sandbox](https://docs.devic.ai/devic/environments/sandbox.md)
>
> The machine agents run commands on, and its snapshots.

> [card] [CLIs](https://docs.devic.ai/devic/environments/clis.md)
>
> Command-line tools baked into the snapshot.

> [card] [Projects](https://docs.devic.ai/devic/projects/index.md)
>
> Environments belong to a project, like everything else.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.