spec

type BoatSandbox struct {
	// Type is the machine size: small, default, large or xlarge.
	Type string `yaml:"type,omitempty" json:"type,omitempty"`
	// Template is the named snapshot an image task starts from.
	Template string `yaml:"template,omitempty" json:"template,omitempty"`
	// Org bills the sandbox to this boat organization.
	Org string `yaml:"org,omitempty" json:"org,omitempty"`
}

type Duration time.Duration

type Expose struct {
	TTL Duration `yaml:"ttl,omitempty" json:"ttl,omitempty"`
	// Via is ExposeViaTailnet or ExposeViaLAN; empty lets the node choose.
	Via   string                 `yaml:"via,omitempty" json:"via,omitempty"`
	Ports map[string]ExposedPort `yaml:"ports,omitempty" json:"ports,omitempty"`
}

type ExposedPort struct {
	Port int    `yaml:"port" json:"port"`
	From string `yaml:"from,omitempty" json:"from,omitempty"`
}

type FileMount struct {
	// Target is the absolute directory it is mounted at, under FilesMount.
	Target string `yaml:"target" json:"target"`
	// Files maps a path relative to Target onto that file's content. Text only: nothing
	// here is executable, and nothing can be a link.
	Files map[string]string `yaml:"files" json:"files"`
}

type Hardening struct {
	ReadOnlyRootfs bool     `yaml:"read_only_rootfs,omitempty" json:"read_only_rootfs,omitempty"`
	Capabilities   []string `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
}

type ModalSandbox struct {
	// Runtime is gvisor or vm; vm has Docker, for sidecars.
	Runtime string `yaml:"runtime,omitempty" json:"runtime,omitempty"`
	// Environment is the Modal environment the sandbox is made in.
	Environment string `yaml:"environment,omitempty" json:"environment,omitempty"`
}

type Readiness struct {
	TCPPort  int      `yaml:"tcp_port,omitempty" json:"tcp_port,omitempty"`
	HTTPPath string   `yaml:"http_path,omitempty" json:"http_path,omitempty"`
	HTTPPort int      `yaml:"http_port,omitempty" json:"http_port,omitempty"`
	Command  []string `yaml:"command,omitempty" json:"command,omitempty"`
	Timeout  Duration `yaml:"timeout,omitempty" json:"timeout,omitempty"`
}

type Resources struct {
	CPU      float64 `yaml:"cpu,omitempty" json:"cpu,omitempty"`
	MemoryMB int     `yaml:"memory_mb,omitempty" json:"memory_mb,omitempty"`
	PIDs     int     `yaml:"pids,omitempty" json:"pids,omitempty"`
}

type Sandbox struct {
	Snapshot string `yaml:"snapshot,omitempty" json:"snapshot,omitempty"`
	// Provider pins the task to that provider's sandbox nodes. Empty is any of them.
	Provider string `yaml:"provider,omitempty" json:"provider,omitempty"`
	// Boat and Modal override that provider's settings for this task's sandbox, when it
	// runs on one.
	Boat  *BoatSandbox  `yaml:"boat,omitempty" json:"boat,omitempty"`
	Modal *ModalSandbox `yaml:"modal,omitempty" json:"modal,omitempty"`
}

type SecretRef struct {
	Name   string `yaml:"name" json:"name"`
	Target string `yaml:"target,omitempty" json:"target,omitempty"`
	Key    string `yaml:"key" json:"key"`
	// Owner is the login a personal secret belongs to. Empty means the secret is global.
	// A stored task from before this field existed has an empty owner and still resolves
	// as global.
	Owner string `yaml:"owner,omitempty" json:"owner,omitempty"`
}

type Sidecar struct {
	Image     string            `yaml:"image" json:"image"`
	Command   []string          `yaml:"command,omitempty" json:"command,omitempty"`
	Env       map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	Readiness Readiness         `yaml:"readiness,omitempty" json:"readiness,omitempty"`
	Resources Resources         `yaml:"resources,omitempty" json:"resources,omitempty"`
	// Privileged runs the sidecar with every capability and no device restriction, which
	// is root on the node's kernel. It exists for one thing — a Docker daemon beside the
	// task, so a turn can run `docker compose` and testcontainers — and the spec only
	// *asks*: a node started without --allow-privileged-sidecars refuses the task at
	// provisioning. Validation lets it through on purpose, because whether a machine will
	// host such a container is an operator's answer and not a parser's.
	Privileged bool `yaml:"privileged,omitempty" json:"privileged,omitempty"`
	// ShareWorkspace mounts the task's workspace volume in the sidecar at the same path
	// the task sees it. A nested daemon resolves a bind-mount source in its OWN
	// filesystem, so a `docker run -v /workspace/...` or a build context under /workspace
	// only works when the daemon sees that path too.
	ShareWorkspace bool `yaml:"share_workspace,omitempty" json:"share_workspace,omitempty"`
}

type TaskSpec struct {
	Image       string             `yaml:"image" json:"image"`
	Command     []string           `yaml:"command,omitempty" json:"command,omitempty"`
	WorkingDir  string             `yaml:"working_dir,omitempty" json:"working_dir,omitempty"`
	Env         map[string]string  `yaml:"env,omitempty" json:"env,omitempty"`
	Secrets     []SecretRef        `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	Sidecars    map[string]Sidecar `yaml:"sidecars,omitempty" json:"sidecars,omitempty"`
	Resources   Resources          `yaml:"resources,omitempty" json:"resources,omitempty"`
	Hardening   Hardening          `yaml:"hardening,omitempty" json:"hardening,omitempty"`
	Labels      []string           `yaml:"labels,omitempty" json:"labels,omitempty"`
	Timeout     Duration           `yaml:"timeout,omitempty" json:"timeout,omitempty"`
	MaxAttempts int                `yaml:"max_attempts,omitempty" json:"max_attempts,omitempty"`
	// RetryOnNodeLoss requeues the task as a new attempt when the node running it goes
	// offline mid-run, instead of marking it lost. It is off by default because a task
	// that is not idempotent must not be silently run twice.
	RetryOnNodeLoss bool `yaml:"retry_on_node_loss,omitempty" json:"retry_on_node_loss,omitempty"`
	// WorkspaceSession is the conversation this volume belongs to. Empty keeps the volume
	// ephemeral: nothing is restored and nothing is uploaded.
	WorkspaceSession string `yaml:"workspace_session,omitempty" json:"workspace_session,omitempty"`
	// WorkspaceRepo names the repository whose base snapshot may seed a session that has
	// none of its own. With WorkspacePublishBase it is also where this task's workspace
	// is published.
	WorkspaceRepo string `yaml:"workspace_repo,omitempty" json:"workspace_repo,omitempty"`
	// WorkspacePublishBase stores this task's workspace as the shared base for
	// WorkspaceRepo. It requires WorkspaceRepo.
	WorkspacePublishBase bool `yaml:"workspace_publish_base,omitempty" json:"workspace_publish_base,omitempty"`
	// WorkspaceReadOnly restores the session's snapshot and stores nothing when the task
	// exits: what it changed is thrown away with the volume. It requires WorkspaceSession,
	// and it does not publish a base.
	WorkspaceReadOnly bool `yaml:"workspace_readonly,omitempty" json:"workspace_readonly,omitempty"`
	// WorkspaceWarm is how long a runtime should stay up after a turn, waiting for the
	// next instruction. Zero means leave when the turn ends. The node publishes it as
	// PODIUM_WORKSPACE_WARM_SECONDS; the runtime is what waits.
	WorkspaceWarm Duration `yaml:"workspace_warm,omitempty" json:"workspace_warm,omitempty"`
	// Expose keeps the task's containers up after its command exits and publishes the named
	// ports outside the node, so people can use what the task built. See docs/task-spec.md.
	Expose *Expose `yaml:"expose,omitempty" json:"expose,omitempty"`
	// Sandbox runs the task in a cloud sandbox instead of a container on the node. See
	// docs/task-spec.md.
	Sandbox *Sandbox `yaml:"sandbox,omitempty" json:"sandbox,omitempty"`
	// Mounts are directories of text files the node writes before the task starts and
	// mounts read-only. See FileMount.
	Mounts []FileMount `yaml:"mounts,omitempty" json:"mounts,omitempty"`
}