Skip to content

Environments and runtimes ​

An environment is a working directory on a machine. Use this page to look up environment specs, saved runtime fields, target spellings, and flow mixins. For guides, see Environments, Runtimes, and Environment roles.

Environment spec ​

Pass one spec per environment role to hmz exec -e. Repeat the flag or separate specs with commas.

text
ROLE=BACKEND[@PROVIDER][/WORKDIR]

The parts of an environment spec: role, backend, optional provider, optional workdirThe parts of an environment spec: role, backend, optional provider, optional workdir

PartRule
ROLEA Python identifier. The name of a role in the flow's EnvCollection. Once per run.
BACKENDOne of local, ssh, docker, swarm, apple-container, slurm.
@PROVIDERThe name of a saved runtime of that backend. For ssh only, a host that is not saved, in brackets: [USER@]HOST[:PORT]. Left off, it is this machine. local takes none. ssh always needs one.
/WORKDIRStarts at the first / after the provider. Absolute, or /~/... for a directory under the home. May be left off only for a runtime saved with a workdir.

Pass the same spec without ROLE= to hmz chat -e, to env in chat.start and chat.move, and to each value of the envs map when an epic starts.

sh
hmz exec -f FLOW -e repo=ssh@build-box/home/alex/shop "add a discount code to checkout"
hmz exec -f FLOW -e repo=ssh@build-box -e scratch=local/tmp/scratch "add a discount code to checkout"
hmz exec -f FLOW -e repo=docker/srv/shop,far=ssh@[alex@far.host:2222]/srv/shop "add a discount code to checkout"
hmz chat -e ssh@build-box/~/shop "what does checkout do?"
SpecWhere the role works
local/srv/shop/srv/shop on this machine.
local/~/shopshop under your home on this machine.
ssh@build-box/home/alex/shopThat directory on the ssh host saved as build-box.
ssh@build-box/~/shopshop under the login's home on that host.
ssh@build-boxThe workdir build-box was saved with.
ssh@[alex@far.host:2222]/srv/shopA host that is not saved.
docker/srv/shopA container on docker's default here, with /srv/shop of this machine mounted.
docker@box/srv/shopA container on the docker runtime saved as box.
swarm/srv/shopA service on the swarm this machine manages.
swarm@cluster/srv/shopA service on the swarm saved as cluster.
apple-container/Users/alex/shopAn Apple container on this Mac.
apple-container@mac/Users/alex/shopOne out of what the runtime saved as mac may hand out.
slurm/lustre/alex/shopA job on the cluster this machine submits to, with the cluster's defaults.
slurm@hpc/lustre/alex/shopA job asked for as the runtime saved as hpc says.

Invalid specs stop hmz exec with exit status 2 and a message that says what is wrong. Deprecated spellings fail the same way, with the current spelling in the message: local@/x, docker@local/x, and an unsaved ssh host written without brackets.

A LocalEnv role uses the directory where the run started and takes no -e. A role declared NotRequired may be left without one.

Backends ​

BackendWhat a role getsCreatedRemoved
localA directory on the machine the daemon runs on. The directory must exist.——
sshA directory on a host reached with the system ssh.——
dockerA container of its own on a docker daemon. The workdir is a directory of the daemon's host, mounted at the same path.When the run opens its environmentsWhen the run closes it
swarmA service of one task on a docker swarm, placed by the swarm's scheduler. The workdir must exist at the same path on every node.When the run opens its environmentsWhen the run closes it
apple-containerA container of Apple's container tool on this Mac: a small Linux virtual machine. No GPUs.When the run opens its environmentsWhen the run closes it
slurmA job of one task on one node, submitted with sbatch. The workdir must be on a filesystem shared by this machine and every node.When the run opens its environmentsCancelled with scancel when the run closes it

Machines reached over ssh require Linux or macOS on x86-64 or aarch64, /bin/sh, and passwordless login. Containers and Slurm nodes require Linux and /bin/sh. You do not need to install anything else on the target.

Saved runtimes ​

Save machines under runtimes.<backend>.<name> in settings.yaml inside the Humanize home. Start each name with a letter or digit, followed by letters, digits, ., _, or -. Omitted fields take their defaults.

yaml
runtimes:
  ssh:
    build-box:
      host: 10.0.0.2
      user: alex
      workdir: ~/shop
      fallback: [docker:box]
  docker:
    box:
      image: python:3.12
      cpus: 8
      memory: 17179869184
      harness: local
  slurm:
    hpc:
      partition: gpu
      max_wait: 600

Common fields ​

FieldTypeDefaultMeaning
workdirstring""Default working directory when the spec omits one. Absolute, or under ~/.
fallbacklist[]Runtimes to try in order when this one cannot hold a role, each <backend>:<name>. Cannot contain itself or duplicates. A fallback runtime does not follow its own fallback list. docker:local, swarm:local, apple-container:local and slurm:local name the default on this machine, unless a runtime is saved as local.
harnessstringenvWhere the agent's CLI runs: env (on the runtime's machine), local (on this machine), or <backend>:<name> (on another saved runtime). Cannot name itself.
madestringtypedOrigin: typed, or imported for an ssh host read from an ssh config.

ssh ​

Set host or alias. Configured fields override your ssh config.

FieldTypeDefaultMeaning
hoststring""Host name or address.
userstring""Login user. Defaults to the ssh config or local user.
portinteger0Port, 0 to 65535. 0 uses the config's port or 22.
identity_filestring""Path to the private key.
proxy_jumpstring""Jump host or hosts.
optionsmap{}Extra ssh options passed as -o KEYWORD=VALUE. Cannot include F, HostName, User, Port, IdentityFile, or ProxyJump: use the fields.
aliasstring""The Host entry imported from an ssh config. ssh resolves it through that config.
configstring""Path to the source ssh config file, if not the default.

docker ​

FieldTypeDefaultMeaning
endpointstringlocalDaemon address. See Docker endpoints.
tls_dirstring""Directory containing ca.pem, cert.pem, and key.pem for a tcp:// endpoint.
imagestring""Default container image when the flow declares none. Falls back to python:3.12-slim.
runtimestring""OCI runtime, such as nvidia. Empty uses the daemon's default.
run_argslist[]Extra arguments for docker run.
name_prefixstring""Container name prefix before the role and 8 hex digits. Defaults to humanize-<name>. Max 54 characters.
cpusnumber0CPUs available to allocate. 0 means all available.
memoryinteger0Bytes of memory available to allocate. 0 means all available.
gpuslist[]GPU device IDs available to allocate.
gpu_memoryinteger0Bytes of memory per GPU. 0 leaves it unspecified.
max_containersinteger0Maximum concurrent containers. 0 means no limit.
containerstring""Name or ID of an existing running container. All roles assigned here share it. Humanize does not start, count, or stop it.
exec_userstring""Numeric UID[:GID] for commands inside the container.
exec_envlist[]NAME=VALUE environment variables for commands inside the container.
exec_wrapperlist[]Command prefix run before every command in the container.

If you set container, do not set image, runtime, run_args, name_prefix, cpus, memory, gpus, gpu_memory, or max_containers.

Run docker inspect to view the resource labels on a container Humanize starts. Each is set only when the environment was given that resource. Humanize reads these labels to total the resources a runtime has allocated:

LabelValue
humanize.cpusCPUs given to the environment.
humanize.memoryMemory in bytes.
humanize.gpusDevice IDs joined by commas, or all.

swarm ​

FieldTypeDefaultMeaning
endpointstringlocalSwarm manager address, written as a docker endpoint.
tls_dirstring""Directory containing ca.pem, cert.pem, and key.pem for a tcp:// endpoint.
imagestring""Default task image when the flow declares none. Every node must be able to pull it.
run_argslist[]Extra arguments for docker service create.
name_prefixstring""Service name prefix. Defaults to humanize-<name>. Max 54 characters.
cpusnumber0Total CPUs tasks may reserve. 0 means all node capacity.
memoryinteger0Total bytes of memory tasks may reserve. 0 means all node capacity.
gpu_resourcestring""Generic resource name nodes use to advertise GPUs, such as NVIDIA-GPU. Empty allocates no GPUs.
constraintslist[]Placement constraints, each <attribute>==<value> or <attribute>!=<value>.
max_tasksinteger0Maximum concurrent tasks. 0 means no limit.
nodesmap{}Map of node hostnames to a saved ssh runtime name or [USER@]HOST[:PORT]. Unlisted nodes connect over ssh at their own address.

apple-container ​

FieldTypeDefaultMeaning
imagestring""Default container image when the flow declares none.
run_argslist[]Extra arguments for container run.
cpusnumber0Total CPUs across containers. 0 means all Mac CPUs.
memoryinteger0Total bytes of memory across containers. 0 means all Mac memory.
max_containersinteger0Maximum concurrent containers. 0 means no limit.

slurm ​

FieldTypeDefaultMeaning
partitionstring""Target partition. Empty uses the cluster default.
accountstring""Billing account. Empty uses your default.
qosstring""Quality of service. Empty uses the default.
timestring""Time limit passed to --time: minutes, MM:SS, HH:MM:SS, D-HH[:MM[:SS]], UNLIMITED, or INFINITE. Empty uses the partition default.
constraintstring""Required node features passed to --constraint.
viastringsrunNode connection method: srun (one job step per connection) or tcp (direct connection to a node port reachable from this machine).
run_argslist[]Extra arguments for sbatch.
cpusnumber0Total CPUs across jobs. 0 means cluster capacity.
memoryinteger0Total bytes of memory across jobs. 0 means cluster capacity.
max_jobsinteger0Maximum queued and running jobs. 0 means no limit.
max_waitinteger0Seconds a job waits for a node before failing. 0 waits indefinitely.
pythonstring""Accepted and ignored. Nodes do not require Python. If set, must be absolute or under ~/.

Docker endpoints ​

Set endpoint on a docker or swarm runtime to one of these values:

SpellingDaemon
localDefault local docker daemon.
unix:///PATHLocal Unix socket.
tcp://HOST:PORTRemote daemon over TCP. Set tls_dir for TLS.
ssh://[USER@]HOST[:PORT]Daemon on an ssh host.
ssh:<name>Daemon on the named ssh runtime.
context:<name>Named docker context.

Target spellings ​

A target identifies a destination machine for hmz internal anchor --target and --harness. See CLI.

SpellingMachine
localThis machine.
local:DIRThis machine, using DIR as the workspace.
ssh://[USER@]HOST[:PORT][?KEYWORD=VALUE&...]Host over ssh. Options pass as -o KEYWORD=VALUE; F sets the config file.
docker://CONTAINER[?user=UID[:GID]&env=NAME=VALUE&exec=WORD][@ENDPOINT]Running container. ENDPOINT is local, unix:///PATH, tcp://HOST:PORT[?tls=DIR], ssh://[USER@]HOST[:PORT][?KEYWORD=VALUE&...], or context:NAME.
apple-container://CONTAINERRunning Apple container on this Mac.
slurm://JOBID[?python=PATH]Node of a running Slurm job. python is accepted and ignored.
tcp://HOST:PORTRunning server listening at this address.
peer://TICKET@HOST:PORTRunning server reached through a rendezvous broker.

Humanize automatically starts its server on local, ssh, docker, apple-container, and slurm targets. tcp and peer targets must already be running.

A tcp:// or peer:// session runs over TLS 1.3 with ALPN hmz-anchor. On startup, the server generates a self-signed P-256 certificate in memory, requiring no configuration or certificate files. Neither side sends the shared secret (--token, --token-file, HUMANIZE_TOKEN, or the peer:// ticket). Instead, each side proves possession with an HMAC bound to the server's public key. Sessions to other targets run unwrapped over a pipe. A server or client built before this TLS layer cannot connect to one built with it.

WARNING

An env option on a docker:// target appears in command lines and logs. Do not pass secrets in it.

Environment mixins ​

Type each role in a flow as Env combined with mixins from hmz.flows. Calling a method from an undeclared mixin raises CapabilityNotGranted. See Flow API for full signatures.

Base Env members:

MemberMeaning
availableWhether the machine was reached and the workdir existed on last check.
backendThe backend (EnvBackendKind).
providerProvider name, or "" for this machine.
roleRole name.
workdirWorking directory for commands.
await env.derive_subdir(subdir=...)Returns an environment in a subdirectory on the same machine, creating it if needed.

Capability mixins ​

MixinAddsThe machine needs
ShellEnvMixinawait env.exec(argv, timeout=0) returns (status, stdout, stderr). Runs directly without a shell. timeout=0 disables the timeout.—
BashEnvMixinexec also accepts a string to run via bash -c.bash
FilesEnvMixinawait env.read(path) returns bytes. await env.write(path, data) writes a full file.—
GitWorktreeEnvMixinawait env.derive_worktree(ref=None, dir=None) returns an environment in a new detached worktree.git
GitEnvMixinawait env.snapshot(name=None), await env.rewind(ref), await env.snapshots().git
RewindableEnvMixinInterface implemented by GitEnvMixin. Declare GitEnvMixin instead.—
TemporaryClonedDirEnvMixinawait env.derive_temp_clone(id), await env.destroy_temp_clone(id): creates and removes a throwaway copy of the workdir.—
ScratchDirEnvMixinawait env.derive_scratch(id), await env.destroy_scratch(id): creates and removes an empty directory on the same machine.—

If a machine lacks a required tool for a mixin, the run fails before starting with CapabilityMissing.

Resource mixins ​

Set these class attributes on the role class to request hardware or images.

MixinAttributeDefaultMeaning
CPUEnvMixin_cpu_count1CPUs.
MemoryEnvMixin_memory0Bytes of memory.
GPUEnvMixin_gpu_count1GPUs.
GPUEnvMixin_gpu_memory0Bytes of memory per GPU.
ImageEnvMixin_image""Container image for docker, swarm, and apple-container. Empty uses the runtime's image, then python:3.12-slim.
BackendHow resources apply
local, sshVerified as minimums before the run starts.
dockerEnforced as hard container limits (--cpus, --memory) and allocated GPU IDs.
swarmSet as service reservations and limits (--reserve-cpu, --limit-cpu, --reserve-memory, --limit-memory, --generic-resource).
apple-containerSets the VM size. Refuses roles that declare GPUEnvMixin.
slurmPassed as job requests (--cpus-per-task, --mem, --gpus).

If a runtime cannot meet these requirements, it moves the role to its fallback or fails with ResourceUnmet.

Open source on github.com/humanfia · RSS: blog · news