Create an environment template

A named, reusable machine configuration that workspaces reference. Requires environments.manage. Secrets are not accepted yet.

Authorization

bearerAuth

AuthorizationBearer <token>

A RemoteHost API key (rh_sk_...) or a user session token.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Match^[a-z0-9][a-z0-9._-]{0,62}$

description?|

Lengthlength <= 1000

isDefault?boolean

Make this the project's default environment. At most one per project.

enforced?boolean

While this is the project's default, every sandbox and workspace execution in the project boots from it, including plain creates that name no environment and existing ones at their next wake: its egress policy, environment variables and setup script apply to all of them, and nobody can choose another environment or template for a new one. A sandbox that already exists keeps its own disk, and so its image. A PATCH that changes only egress posture -- this flag, egressPolicy, egressAllowlist -- needs environments.egress.manage, and a change that mixes posture with anything else needs both. Which environment is the default is authoring (environments.manage), and a default move, unset or delete that starts or ends enforcement -- including making a still-flagged environment the default again -- also needs environments.egress.manage; each is recorded on the audit log.

templateId?|

A template id or name, the org's own first, then the platform's. Null for the standard image.

machineSize?|

Value in

"small"
"default"
"large"
"xlarge"
null

vmm?|

The VMM (virtual machine monitor) its sandboxes run on. Null or left out: its template's, else the org's default. Refused with 409 vmm_mismatch when its custom template is built for another VMM. Refused with 400 until VMM choice is enabled for this deployment.

Value in

"qemu"
"firecracker"
null

setupScript?|

Runs on every fresh or cold boot, as the sandbox user from /code, after the checkout and before the agent, for at most 30 minutes with no stdin; output goes to ~/.remotehost-setup.log. Must be idempotent: a cold boot re-runs it on the same disk. At most 65536 bytes. Refused if it contains what looks like a credential.

services?array<>

Long-running commands, each started (where services are enabled; rolling out) after the setup script on every create and cold boot, as the sandbox user from cwd (default /code), with the environment variables and no stdin; output goes to ~/.remotehost/services/.log. A resume from memory keeps them running; one that exits is not restarted. A command must stay in the foreground: one that daemonizes (pg_ctl start, docker compose up -d) reports as exited. Commands that look like they contain a credential are refused.

Itemsitems <= 16

ports?array<>

Ports to expose to the project's team: each sandbox lists them with a team preview ready to open (GET /sandboxes/{sandboxId}/ports). Nothing is made public.

Itemsitems <= 32

envVars?

Non-secret configuration. Names and values that look like credentials are refused; secrets will be stored in the credential vault.

egressPolicy?string

none: no network. trusted (default): package registries, git providers and model APIs, plus egressAllowlist. full: the open internet. custom: egressAllowlist only.

Value in

"none"
"trusted"
"full"
"custom"

egressAllowlist?array<string>

Domains, like registry.npmjs.org or *.example.com. Only with trusted or custom.

Itemsitems <= 256

Response Body

`application/json`

curl -X POST "https://example.com/orgs/string/projects/string/environment-templates" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "environment": {    "usage": {      "workspaces": 0,      "sandboxes": 0    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "name": "string",    "description": "string",    "isDefault": true,    "enforced": true,    "template": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "platform": true    },    "machineSize": "small",    "vmm": "string",    "setupScript": "string",    "services": [      {        "name": "string",        "command": "string",        "port": 1,        "cwd": "string"      }    ],    "ports": [      0    ],    "envVars": {      "property1": "string",      "property2": "string"    },    "egressPolicy": "none",    "egressAllowlist": [      "string"    ],    "applied": true,    "createdAt": "string",    "updatedAt": "string"  },  "egressPropagation": {    "applied": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "name": "string"      }    ],    "failed": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "name": "string",        "error": "string",        "stopped": true      }    ],    "notRunning": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "name": "string"      }    ],    "listError": "string"  }}

Create an environment template

Authorization

Path Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

408application/json

409application/json

413application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`