Orgo - Cloud computers for AI agents

A template is a single orgo.ai/v1 document, written in YAML or JSON. This page is the field-by-field reference. The canonical machine-readable contract is the JSON Schema at GET /api/template-schema. Point your editor at it for autocomplete and inline validation.

# yaml-language-server: $schema=https://www.orgo.ai/api/template-schema

The published JSON Schema describes the canonical form only. It requires api_version and template, and it rejects unknown top-level keys. An editor validating against it therefore flags every sugar document as invalid on two counts. Sugar is desugared server-side, so check a sugar template with Validate template instead of relying on editor validation.

Two forms

Templates accept a canonical form and a shorter sugar form. Both normalize to the same document and the same digest.

api_version: orgo.ai/v1
template:
  name: my-workstation
  version: 1.0.0
hardware:
  cpu: 2
  ram_gb: 4
  resolution: 1280x800x24
env:
  NODE_ENV: production
files:
  - to: /opt/welcome.txt
    inline: "hello"
hooks:
  on_resume: |
    echo "ready"

name: my-workstation@1.0.0
cpu: 2
ram: 4gb
display: 1280x800
wallpaper: "https://example.com/bg.jpg"

env:
  NODE_ENV: production

files:
  /opt/welcome.txt: "hello"

on_resume: |
  echo "ready"

Sugar → canonical

Sugar	Canonical
`name: foo@1.0.0`	`template: { name: foo, version: 1.0.0 }`
`version:`, `description:`, `publisher:`	the matching `template` field
`cpu: 2`	`hardware: { cpu: 2 }`
`ram: 4gb`	`hardware: { ram_gb: 4 }`
`disk: 30gb`	`hardware: { disk_gb: 30 }`
`display: 1280x800`	`hardware: { resolution: 1280x800x24 }`, where depth defaults to `24`
`gpu: t4` / `audio: true`	the matching `hardware` field
`bandwidth: 500`	`hardware: { bandwidth_mbps: 500 }`
`files: { /path: "text" }`	`files: [{ to: /path, inline: "text" }]`
`files: { /path: { from: …, mode: … } }`	`files: [{ to: /path, from: …, mode: … }]`
`apps: { server: "cmd" }`	one app named `server` with one `restart: always` service running `cmd`
`on_resume: \|`	`hooks: { on_resume: … }`, with the same shortcut for the other four hooks
`wallpaper: "https://…"`	a `files` entry downloading the image to `/usr/share/backgrounds/wallpaper.jpg`, plus an `on_every_boot` hook that sets it as the XFCE background. That hook runs during the build’s cold boot, so the wallpaper is baked into the golden snapshot

A canonical block always wins: if a document sets both hardware.cpu and top-level cpu, the hardware value is used and the sugar key is ignored. ram and disk accept 4gb, 4g, or a bare 4; a sub-gigabyte size such as 512mb resolves to 0, which is the same as omitting it.

Top-level fields

Field	Type	Required	Description
`api_version`	string	yes	Must be `orgo.ai/v1`. Any other value is rejected with code `unknown_api_version`.
`template`	object	yes	Identity: name, version, description.
`hardware`	object	no	Computer resource shape. Omitted, every hardware field takes its default.
`secrets`	array	no	Vault secrets the template needs. Max 64.
`vars`	map	no	Variables for `${var.X}` interpolation.
`env`	map	no	Environment variables, literal or secret-backed.
`build`	object	no	Build-time install steps.
`files`	array	no	Files written into the computer. Max 256.
`apps`	array	no	Apps, services, and health checks. Max 64.
`triggers`	array	no	Reactive automation. Max 256.
`terminal`	array	no	Pre-staged tmux sessions. Max 32.
`hooks`	object	no	Lifecycle shell hooks.
`telemetry`	object	no	Metrics and logs.
`egress_policy`	object	no	Per-computer network rules. Omitted, no filtering is applied.
`streaming`	array	no	Outbound RTMP streams. Max 16.

Every field except api_version and template is optional, so the smallest valid template is a name, a version, and the API version.

template

Identity and provenance. name and version are required.

template:
  name: claude-code          # lowercase kebab-case, 1-64 chars
  version: 1.0.0             # semver, immutable once published
  description: Claude Code CLI, ready in the terminal.
  publisher: orgo            # optional handle (kebab-case)
  license: MIT               # optional SPDX id (informational)
  homepage: https://…        # optional
  source: https://github.com/…  # optional

hardware

The computer’s resource shape. Every field is optional; omit one and the platform default applies. A Create computer request overrides these at launch.

Field	Type	Values	Notes
`os`	string	`linux`	Linux only.
`cpu`	integer	`1`, `2`, `4`, `8`, `16`	vCPU count. Any other value is rejected. Capped by your plan.
`ram_gb`	integer	`4`, `8`, `16`, `32`, `64`	RAM in GB. Any other value is rejected. Capped by your plan.
`disk_gb`	integer	≥ 1	Disk in GB.
`gpu`	string	`none`, `t4`, `l4`, `a10`, `l40s`, `a100-40`, `a100-80`, `h100`	GPU model.
`gpu_count`	integer	≥ 0	Number of GPUs.
`resolution`	string	`WIDTHxHEIGHTxDEPTH`	e.g. `1280x720x24`. All three parts are required in the canonical form.
`auto_stop_minutes`	integer	`0`-`1440`	Idle minutes before the computer auto-stops. `0` disables auto-stop.
`region`	string	`auto-us`, `iad`, `sjc`, `lax`	Placement region.
`audio`	boolean	`true` / `false`	Enable the audio device. Defaults to `false`.
`bandwidth_mbps`	integer	≥ 0	Network bandwidth cap in Mbps.

vars and interpolation

vars are compile-time strings, interpolated across the document before build.

vars:
  region: sjc2
  tag: v7

env:
  REGION: "${var.region}"

files:
  - to: /opt/config
    inline: "region=${var.region} tag=${var.tag}"

${var.X} resolves from vars.
${env.X} resolves from a literal env value (not secret-backed ones).
$${var.X} escapes to a literal ${var.X}.
An unknown reference is a validation error with the exact field path.

env

Environment variables written to the computer. Keys must be UPPER_SNAKE_CASE. Each value is a literal string, or a {secret: <name>} reference resolved from the launching user’s vault at create time. A value cannot be both.

secrets:
  - name: anthropic_api_key

env:
  NODE_ENV: production
  ANTHROPIC_API_KEY:
    secret: anthropic_api_key

A {secret: …} reference to a name you never declared under secrets is a validation error (unknown_reference). See Secrets for the full secret-injection model.

build

Package and command steps run once when baking the golden snapshot, before app installs. This is where dependencies get pre-installed so launches are instant.

build:
  apt: [ffmpeg, ripgrep]
  pip: [requests, httpx]
  npm: [pnpm]
  run:                      # up to 64 shell commands, in order
    - curl -fsSL https://example.com/install.sh | bash

files

Files materialized into the computer. Each entry sets exactly one of from or inline. Setting both, or neither, is a validation error.

files:
  - to: /opt/hello.txt
    inline: "hello world"

  - to: /usr/share/backgrounds/bg.png
    from: https://example.com/bg.png   # http, https, git, s3, file, or secret://

  - to: /opt/run.sh
    mode: "0755"                        # octal permissions
    inline: |
      #!/bin/bash
      echo hi

  - to: /root/.config/app.json
    from: secret://app_config           # pulled from the vault
    when: runtime                        # build (default) or runtime

Field	Required	Description
`to`	yes	Absolute destination path (or `~/…`). No `..`, no reserved system paths.
`from`	one of	Source URI: `file`, `git`, `http`, `https`, `s3`, or `secret://<name>`.
`inline`	one of	Inline file content.
`mode`	no	Octal permissions, 3 or 4 digits, e.g. `"0644"`. Omitted, the default mode applies.
`owner` / `group`	no	Ownership, resolved against the computer’s `/etc/passwd`.
`when`	no	`build` (the default, baked into the snapshot) or `runtime` (re-applied each boot).

to must be an absolute path with no ... Reserved system paths are rejected: /proc, /sys, /boot, /dev, /tmp, /run, plus the Orgo runtime (/etc/orgo, /var/orgo, /orgo, /etc/supervisor, and Orgo’s own binaries under /opt and /usr/local/sbin). Your apps can still write under /opt and elsewhere. Only Orgo’s own runtime files are off-limits.

apps

An app bundles an install step with the long-running services, health checks, and ports it needs. Services are managed by supervisord, so they start at boot and respawn on crash.

apps:
  - name: my-app
    title: "My Application"
    install: |
      npm install -g my-app
    services:
      - name: my-app-server
        run: "my-app serve --port 8000"
        cwd: /opt/my-app
        user: root            # default: orgo (unprivileged)
        restart: always       # always | on-failure | no
        env:
          PORT: "8000"
    health:
      type: http              # http | tcp | command | process
      url: http://127.0.0.1:8000/health
      every: 15s
      timeout: 3s
      retries: 3
      on_fail: restart_service:my-app-server
    ports:
      - { internal: 8000, public: true }
    autostart:
      - { run: "firefox http://localhost:8000", delay: 3 }

App name is required and must be unique kebab-case. requires lists other app names this one depends on, and data lists persistent data paths, validated the same way as files[].to.

services

Field	Required	Description
`name`	yes	Unique service name (kebab-case), unique across all apps.
`run`	yes	The long-lived command.
`cwd` / `user` / `env`	no	Working directory, run-as user, and extra environment variables for this service.
`restart`	no	`always` (default), `on-failure`, or `no`.
`stop_signal` / `log`	no	Stop signal (e.g. `TERM`) and log file path.

health

A polled liveness check. After retries consecutive failures, on_fail runs. This is the per-app watchdog. type is required; the other fields are optional.

`type`	Checks
`http`	`url` returns 2xx/3xx
`tcp`	`port` accepts a connection
`command`	`command` exits `0`
`process`	`process` name is running

every defaults to 30s, timeout to 5s, and retries to 3. All durations are Go duration strings (30s, 2m, 1h). on_fail is one of restart_service:<name>, restart_vm, alert, or none.

ports

Field	Required	Description
`internal`	yes	In-computer port, 1-65535. `5900`, `5999`, `6080`, and `8080` are reserved by the Orgo runtime and rejected.
`external`	no	Externally mapped port. `0` (the default) means none.
`protocol`	no	`tcp`, `udp`, `http`, or `ws`.
`public`	no	Expose publicly. Defaults to `false`. When `true`, the host port is returned in the computer’s `template_ports`.

terminal

Pre-staged tmux sessions, created detached at first boot. Orgo’s browser terminal attaches to them by name. name is required and must be unique.

terminal:
  - name: logs
    title: "Service Logs"
    cwd: /opt/my-app
    run: "tail -F /var/log/orgo/my-app.log"

Sessions are not auto-restarted. For a process that must respawn, use an app service instead.

hooks

Shell that runs at lifecycle points. Each runs with set -e; the default timeout is 10 minutes per hook.

Launching a built template is a golden-snapshot restore, and a restore never re-runs the cold-boot init. on_first_boot and on_every_boot fire only on a cold boot, which for a built template means the build itself. Neither runs on a normal launch. on_resume is the only hook that runs on every launch.

Hook	When
`on_first_boot`	Once, on the computer’s first cold boot. Skipped entirely on a golden restore.
`on_every_boot`	On every cold boot. Does not run on a golden restore, so never on a normal template launch.
`on_pre_snapshot`	In the build computer, immediately before the golden snapshot is captured. Use it for cleanup, e.g. `apt-get clean`.
`on_resume`	After a restore from the golden snapshot. This is the one hook that runs on every launch. `/root/.env` is sourced first, so create-time secrets are already in the environment.
`on_shutdown`	On graceful shutdown.

hooks:
  on_pre_snapshot: |
    apt-get clean
  on_resume: |
    echo "restored at $(date)"

on_resume is the right place for per-computer work that depends on launch-time state, like a freshly injected secret. See Secrets. Work that should be baked into the image belongs in build or an app’s install, not in a boot hook.

telemetry

telemetry:
  metrics: true               # flag the computer as scrape-ready
  logs: [my-app-server]       # service log paths/names to ship
  otel_endpoint: https://otel.example.com   # push OTLP metrics + logs

egress_policy

Per-computer network filtering, enforced on the host. Both mode and rules are required when the block is present.

egress_policy:
  mode: allow                 # allow = only these reachable; block = everything except these
  rules:
    - "*.github.com"
    - "api.anthropic.com"
    - "10.0.0.0/8"

Rules are domain patterns, exact domains, IPs, or CIDRs. Domain patterns match at the DNS layer, so *.github.com also covers subdomains. The VNC and Desktop API paths are always reachable. Omit the block entirely for no filtering.

streaming

Outbound RTMP(S) streams of the desktop. name, url, and key are required; url must start with rtmp:// or rtmps://.

streaming:
  - name: live
    url: rtmps://ingest.example.com/app
    key:
      secret: stream_key       # literal string or a vault secret
    autostart: true            # defaults to false

streaming is parsed and validated today; the runtime streamer is rolling out. Track status in the JSON Schema.

Next steps

Secrets

The full secret-injection model.

Triggers

Sources, actions, and dedup.

Examples

Annotated real templates.

Publish API

Ship a template over HTTP.

Get Started

Guides

Migrations

Templates

Model integrations

Template schema

Two forms

Sugar → canonical

Top-level fields

template

hardware

vars and interpolation

env

build

files

apps

services

health

ports

terminal

hooks

telemetry

egress_policy

streaming

Next steps

Secrets

Triggers

Examples

Publish API

​Two forms

​Sugar → canonical

​Top-level fields

​template

​hardware

​vars and interpolation

​env

​build

​files

​apps

​services

​health

​ports

​terminal

​hooks

​telemetry

​egress_policy

​streaming

​Next steps

Secrets

Triggers

Examples

Publish API

Two forms

Sugar → canonical

Top-level fields

template

hardware

vars and interpolation

env

build

files

apps

services

health

ports

terminal

hooks

telemetry

egress_policy

streaming

Next steps