SpensCustom environments
How to write environment templates for spens
You can add your own environment templates in two ways:
- Put JSON template files in a
templates/directory inside your workspace. Local templates take precedence over built-in templates with the same name. - Pass a
.jsonfile directly as the environment argument. The path is resolved relative to the current directory or the workspace.
Environment template format
An environment template is a JSON file with "template_type": "environment". It defines the base Docker image, system packages, and the nono.sh installation.
| Field | Required | Description |
|---|---|---|
template_type | yes | Must be "environment" |
name | yes | Name used on the command line |
base-image | yes | Docker base image for the environment |
nono-command | yes | Shell command that installs the nono shell in that image |
packages | no | Additional system packages to install |
package_manager | no | Package manager used to install packages: apt (default) or apk |
nono_base_config | no | nono.sh base profile to pull and extend. Omit to use only the agent's profile |
agent_user | no | The unprivileged user the agent runs as: {"name", "uid", "home", "create"}. Defaults to a created spens user (uid 1000, home /home/spens). The node environments reuse the image's existing node user. Paths in agent templates starting with ~ expand to this user's home |
Worked example: a custom Go environment
Create templates/go-1.24.json in your workspace:
{
"template_type": "environment",
"name": "go-1.24",
"base-image": "golang:1.24-bookworm",
"nono-command": "curl -fsSL https://nono.sh/install.sh | sh",
"packages": ["curl", "ca-certificates", "git"],
"package_manager": "apt",
"agent_user": {
"name": "spens",
"uid": 1000,
"home": "/home/spens",
"create": true
}
}Then run it by name (picked up from templates/) or by file path:
spens go-1.24 pi .
spens go-1.24.json pi .