Skip to content

Environments API

Beta. List, create, change and rebuild the Environments your computers start from.

An Environment is what a computer starts from: the repositories it clones, a setup script, and the tools it installs. Dexto builds it once and starts new chats from the ready build. This API is in beta.

An Environment belongs to a person in an organization, not to a Cloud project, so it takes that person’s OAuth token, such as the one dexto login stores. An API key gets 403. Reads need cloud:read or cloud:write; writes need cloud:write. You can do what Settings lets you: a member changes only their own personal Environments, Owners and Admins change team ones, and another member’s personal Environment is 404.

POST /v1/environments
Terminal window
curl -X POST https://api.dexto.ai/v1/environments \
-H "Authorization: Bearer $DEXTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Dexto dev",
"visibility": "team",
"spec": {
"repos": [{ "repository": "truffle-ai/dexto", "ref": "main" }],
"setup_script": "pnpm install",
"tools": [{ "name": "oxfmt", "install": "npm i -g oxfmt" }],
"network": { "mode": "full" },
"variables": [{ "name": "APP_ENV", "value": "local" }]
}
}'

The response is the Environment, and its first build is queued.

FieldRules
nameThe Environment’s name.
visibilitypersonal (only you) or team (the organization’s members). Defaults to personal.
specrepos, setup_script, tools, network, services and variables. It holds no secret values; builds reach private registries through your connections.

variables are visible, non-secret settings such as APP_ENV=local: up to 50, each an uppercase name and a one-line value of at most 4 KiB (8 KiB for all values together). The setup script, tools, services and the computer’s login shells see them, and anyone who can read the Environment sees their values, so never put a secret in one. Names Dexto sets on the computer, such as PATH, HOME, the proxy variables and anything starting with DEXTO_, are refused.

state says where it stands: building while a build is queued or runs, ready when the ready build matches the spec, out_of_date when it doesn’t, failed when the latest build failed and none is ready, and none before any build.

GET /v1/environments
GET /v1/environments/{environment_id}
PATCH /v1/environments/{environment_id}

A list holds every team Environment and your own personal ones. PATCH changes any of name, visibility and spec; a new spec replaces the whole one and queues a build. Deleting an Environment and choosing the organization default stay in Settings.

POST /v1/environments/{environment_id}/rebuild
GET /v1/environments/{environment_id}/builds
GET /v1/environments/{environment_id}/builds/{build_id}

A rebuild queues a build of the current spec, or joins the one already queued, and answers 202 with that build. The last ready build stays in use until the new one is ready, so a failed rebuild never breaks new chats. The build list holds the latest 20, newest first; one build also returns its log, the last 64 KiB, so you can follow it while it runs.

const dexto = createCapabilitiesClient({ token });
const environment = await dexto.environments.create({
name: "Dexto dev",
spec: { repos: [{ repository: "truffle-ai/dexto" }] },
});
const build = await dexto.environments.rebuild(environment.id);
const { log } = await dexto.environments.getBuild(environment.id, build.id);

dexto.environments also has list, get, update and listBuilds. See /v1/openapi.json for every schema and error.