# Managed images

Understand the managed sandbox image and the configuration builders control.

Salambo deployments use managed images. This gives the platform authority over runtime compatibility, security updates, isolation, and immutable base-image provenance.

## Configuration

Declare managed mode in `salambo.yaml`:

```yaml
image:
  mode: managed
```

A local project Dockerfile is not used by the hosted build.

## What builders control

| Need                         | Supported surface       |
| ---------------------------- | ----------------------- |
| Agent behavior               | `.pi/`                  |
| New-run workspace seed       | `sandbox/workspace/`    |
| Supported runtime packages   | `sandbox/packages.json` |
| Region, networking and state | `runtimeConfig`         |
| Environment and secrets      | `env` and `secrets`     |

Salambo combines those inputs with an approved immutable runtime base and records the resulting deployment provenance.

## Add runtime packages

Declare packages in `sandbox/packages.json`:

```json
{
  "version": 1,
  "apt": ["poppler-utils"],
  "npm": ["cowsay@1.6.0"],
  "pip": ["rapidfuzz==3.10.1"]
}
```

The file is declarative. It does not accept shell commands, lifecycle configuration, URLs, version ranges, or extra fields. npm and Python entries require exact versions. APT entries accept package names or exact `name=version` specifications.

Salambo validates the file locally and again in the deployment worker. The worker installs the packages once while building the immutable managed image. It does not reinstall them for each run or turn.

At runtime:

* APT binaries are available on the normal command path.
* npm command-line binaries are added to `PATH`.
* Python modules are available through the standard Python import path.
* The managed language-package directory is read-only to agent tools.
* Image configuration and package data under `/etc` and `/var` are read-only.
* Platform runtime paths remain hidden from agent tools.

Managed packages are intended for command-line tools and libraries. Packages that require a long-running system service or persistent writes outside `/workspace` are not supported.

Changing `sandbox/packages.json` requires a new deployment. Existing deployments and running workspaces keep their current image.

If validation fails, the deployment stops before the remote build. If a package manager cannot install a declared package, the deployment fails at the image-build stage with `sandbox_package_install_failed`. The previously active deployment remains active.

## Runtime updates

When the run Details view shows **Runtime update recommended**, deploy the agent again so it receives the current managed runtime. Treat that warning as upgrade work; do not depend on an older runtime image as a permanent execution environment.

Continue with [environment variables and secrets](/docs/deploy/environment-secrets) or [networking and regions](/docs/deploy/networking-regions).