Sandbox & Environments
The bundled Environments plugin provides two things: safer command execution for accounts without operator authority, and persistent environments for managed Projects. For the everyday workflow, see Projects, Environments & GitHub.
Where to manage environments
- Settings → Plugins → Environments contains the host readiness panel and instance-wide defaults.
- Open a managed Project and choose Environments to start or stop its environment, view resource use and logs, create or restore snapshots, and manage shared worktrees.
- Users → account → Development environment shows that account's private HOME, execution mode, active processes and Git author. Administrators can reset the HOME there.
The plugin adds no slash command.
Environment tools
| Tool | What it does |
|---|---|
EnvironmentStatus | Reads a managed Project's state and limits without starting it. |
EnvironmentStart / EnvironmentStop | Requests a start or stop. Stopping interrupts project services and running commands. |
EnvironmentSnapshot / EnvironmentRestore | Saves a crash-consistent snapshot or replaces the environment with one. Restore requires explicit confirmation. |
EnvironmentLogs | Reads bounded lifecycle logs and the guest system journal. |
EnvironmentOperation | Checks whether a requested operation is still pending or has finished. |
EnvironmentWorktrees | Lists, creates or removes organizational worktrees in the shared Project environment. |
These tools work only with managed Projects. A requested operation may still be pending when the tool returns; check it with EnvironmentOperation.
Enable the plugin and set defaults
The plugin is bundled and enabled by default. It is not user-grantable. Its environment tools also require access to the managed Project. Saving plugin settings or enabling or disabling a plugin requests an Elowen restart, announced as Restart.
Under Settings → Plugins → Environments, administrators can set defaults for newly provisioned environments:
| Setting | Config key | Default | Range |
|---|---|---|---|
| Confine non-operator commands | confineNonOperators | On | On or off |
| Processor | defaultCpus | 1 CPU | 0.1–64 CPU |
| Memory | defaultMemoryMb | 1,024 MiB | 128–65,536 MiB |
| Processes | defaultPidsLimit | 512 | 32–8,192 |
| Default network mode | defaultNetworkMode | Shared outbound network | Shared or isolated |
Shared networking provides outbound internet through a private machine link; isolated mode permits only the environment's loopback traffic. Administrators can also set inbound TCP or UDP port forwarding on the Project; the host port is not exposed on host loopback. Resource and network defaults apply when an environment is first provisioned. Administrators can change limits and networking for an existing Project on its Environments page. Resource changes apply without a restart; changing network mode briefly stops and restores the environment. A disk ceiling is configured per Project, not in these defaults. Passing it stops the environment.
Account HOME and command execution
Each linked account has a private HOME for Git, npm and tool configuration. It is separate from Projects. Administrators can set the Git author name and email on the account's Development environment page. Resetting the HOME removes its configuration, first previews what will be lost, requires a typed confirmation phrase and is blocked while the account has active processes.
Commands from accounts without operator authority run in a restricted bubblewrap environment by default. They can access their available Project directories and account HOME, and retain network access. If the live containment check fails, the command is refused. An administrator can turn off Confine non-operator commands, which allows those accounts to run commands directly on the host.
An operator running commands outside a managed Project uses the host directly. A managed Project's commands run inside its own environment; this is separate from the account's host execution setting. Background commands started by plugins remain confined. Only confined terminal sessions receive the account's GitHub credential, and output containing the credential is redacted.
Persistent Project environments
Each managed Project has one persistent systemd-nspawn environment. The host must be prepared before a new environment can be created. The Host runtime panel reports missing requirements; an administrator can choose Prepare host there. The host retrieves and verifies a published root filesystem when it is needed. The environment is provisioned on demand and keeps its files and installed packages when stopped. It reports one of these states: not provisioned, starting, running, stopped, failed, deleting or deleted.
Start, stop, snapshot and restore actions are durable requests. They return an operation that may still be running; check its status before assuming it completed. Retrying an interrupted request with the same request ID avoids queuing it twice. An expected generation can prevent acting on an environment that changed since it was read. Logs are limited to 1,000 lines. Snapshot captures the root filesystem, HOME, worktrees and data while execution is paused. A note can describe the snapshot, up to 2,000 characters. It is crash-consistent, not database-consistent, so export application databases separately when needed. Project snapshots include every component.
Restore replaces the environment with the selected snapshot in a fresh generation. It discards changes made after that snapshot and interrupts running work, so it requires explicit confirmation. Deleting a Project also deletes its environment. Transfer or delete any published Sites first.
Organizational worktrees are shared by everyone with access to the Project. Their branches are named elowen/<label>-<suffix>. They separate work but are not security-isolated and do not select the execution target for a conversation. Before removing one, preserve uncommitted files and commits that are not already reachable from another branch. Create native Git worktrees for isolated repository work; see Projects, Environments & GitHub.
Access and limits
Project access is checked when an environment operation runs. Only administrators can manage host readiness, account HOME settings, and a Project's resource limits.
- Snapshots are crash-consistent, not database-consistent.
- Resource defaults affect new environments only; limits for existing environments are changed on the Project.
- Creating an environment requires a prepared host and an available, verifiable root filesystem. The host readiness panel reports what needs attention; the first start is refused if a requirement is missing.
- The administrator sets each Project's CPU, memory, process and disk limits. Disk ceilings start at 1,024 MiB and go up to the measured disk capacity in 1,024 MiB steps. Disk usage above the ceiling stops the environment; free space or raise the ceiling before starting it again.
- Inbound forwarding supports TCP or UDP. Host ports must be 1,024–65,535; environment ports can be 1–65,535.
- Environment tools do not manage Sites or host Projects.
For plugin administration, see Plugins.