Setup and dependencies

Magmell prepares dependencies while building a deployment, before any run starts. The resulting filesystem is part of that immutable version and is reused by every run of it.

Python dependencies

Place a conventional requirements.txt beside handler.py:

requirements.txt

openai==1.93.0
httpx==0.28.1
pydantic==2.11.7

The CLI uploads the file with the rest of the directory. When no explicit API requirements are provided, Magmell installs it with:

python -m pip install --no-cache-dir -r /app/requirements.txt

magmell deploy ./agent --name document-agent --version 1 --wait

The TypeScript SDK can instead supply explicit requirements. A non-empty explicit list takes precedence over requirements.txt:

await magmell.deploy({
  name: 'document-agent',
  version: '1',
  dir: './agent',
  requirements: ['openai==1.93.0', 'httpx==0.28.1'],
})

Node.js dependencies

For a node-22 deployment, put package.json and its npm lockfile v3, package-lock.json, beside handler.ts. Magmell runs the pinned platform npm with:

npm ci --omit=dev

The two package files must either both be present or both be absent. Commit the lockfile and pin the in-handler SDK exactly as a development dependency:

package.json

{
  "engines": { "node": ">=22 <23" },
  "dependencies": {
    "zod": "3.25.76"
  },
  "devDependencies": {
    "@siloga/magmell-agent": "0.1.0"
  }
}

The platform validates that the SDK version is compatible and injects its protected copy after installing production dependencies. npm workspaces, a root binding.gyp, non-npm package managers, and root install lifecycle scripts are not supported. Use setup steps for explicit build preparation. Do not send the Python requirements field with a Node deployment.

System setup

Use ordered setup steps for operating-system packages, downloaded assets, code generation, or other build preparation:

magmell deploy ./video-agent \
  --name video-agent \
  --version 1 \
  --setup 'apt-get update' \
  --setup 'apt-get install -y ffmpeg' \
  --wait

The SDK accepts the same commands as an array:

await magmell.deploy({
  name: 'video-agent',
  version: '1',
  dir: './video-agent',
  setupSteps: [
    'apt-get update',
    'apt-get install -y ffmpeg',
    'sh setup.sh',
  ],
})

Setup steps run with administrative privileges inside the isolated build environment. Treat them as trusted deployment code: review scripts and install commands before creating a version. The handler itself runs under the platform runtime identity after the build completes.

Build order

For a Python handler deployment Magmell performs these operations:

1. Start from the Python 3.12 build image.
2. Copy deployment files and the Magmell runtime into /app.
3. Execute each setup step in order with /app as its working directory.
4. Install explicit requirements, or fall back to requirements.txt.
5. Configure and snapshot the handler runtime.

For a Node.js 22 handler Magmell instead:

1. Starts from the pinned linux/amd64 Node.js 22 build image.
2. Copies the deployment files into /app.
3. Executes each setup step in order with /app as its working directory.
4. Verifies the protected Node/npm bootstrap and runs npm ci --omit=dev when package files exist.
5. Compiles handler.ts, installs the protected agent runtime, removes build-only material, and snapshots the final non-root runtime.

A step that exits non-zero stops the build. The deployment becomes build_failed, and its build logs contain the setup output.

Each step uses a separate shell. Filesystem changes persist, but an exported shell variable does not automatically carry into the next step. Put related commands in one step or a checked-in setup.sh when they need the same shell environment.

For Node deployments, setup commands run before npm dependency installation. Files they create in /app are available to the install and compile phases. No customer-controlled command runs during the build after the final protected runtime assembly. (A command deployment’s entrypoint runs later at invocation, not during the build; see command deployments.)

Network and credentials

Build networking is managed by the execution environment. Production builds are intended to reach public package repositories, but Magmell does not currently expose or enforce a per-domain build allowlist. Local Docker builds use the Docker daemon’s configured network.

Do not rely on setup commands being able to reach private or internal services. If a build needs an authenticated resource, publish it through a suitable package or artifact repository, or fetch it at run time using a deployment secret.

Deployment secrets are deliberately unavailable during the build. Do not place credentials in setup commands, source files, URLs, or requirements files: all of those become part of the stored deployment manifest or build output.

Reproducible builds

• Pin dependency versions that affect production behavior.
• Prefer authenticated downloads at run time when they require deployment secrets.
• Keep setup scripts in the deployed directory so changes are reviewable.
• Create a new deployment version whenever requirements or setup steps change.

Setup commands and their order are part of the artifact identity. Changing only one step produces a different build rather than silently reusing an older template.