Replace environment

Saves one codebase's install and start scripts.

PUT /v1/environment/{repo}

Environment → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/environment/{repo}`
Method	`PUT`
Operation	`put_environment_by_repo`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Saves one codebase's install and start scripts.

Every later sandbox run on this codebase runs the install script in its fresh checkout before the agent starts, and leaves the start command running in the background. Saving clears any pending proposal: saving is the review. Secrets are set one at a time on their own address and are left as they are. Org admin only.

Request

4 fields, body application/json (required).

Field	In	Type	Required	Description
`repo`	path	string	yes	Repo is the repository's name in the caller's org.
`install`	body	string	—	Install is run in every fresh checkout before the agent starts, from the repository root, and must be non-interactive.
`repo`	body	string	—	Repo is the repository's name in the caller's org.
`start`	body	string	—	Start is left running in the background after the install.

Response

Status	Body	Meaning
`200`	environment.Environment	ok
`default`	problem-details	refused

200 body — 12 fields.

Field	In	Type	Always	Description
`install`	body	string	—	Install is the shell a run executes in its fresh checkout before the agent starts, from the repository root.
`proposal`	body	environment.Proposal	—
`proposal.install`	body	string	—	Install is the install script the agent checked.
`proposal.note`	body	string	—	Note is what the agent found and checked, in its own words.
`proposal.secrets`	body	string[]	—	Secrets are the environment variables the agent found the codebase reads.
`proposal.start`	body	string	—	Start is the start command the agent checked, or empty.
`repo`	body	string	—	Repo is the codebase: a repository's name in the caller's org.
`secrets`	body	string[]	—	Secrets are the names set on this codebase, each exported to the run's commands under that name.
`session`	body	string	—	Session is the setup run that produced the proposal, when there is one.
`start`	body	string	—	Start is the one command a run leaves running in the background once the install has finished — a dev server, a database.
`state`	body	string	—	State is `none` when nothing is saved or proposed, `proposed` when a setup run's answer is waiting to be reviewed, and `ready` otherwise.
`updatedAt`	body	string	—	UpdatedAt is when this environment last changed, RFC 3339.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

.ts

.py

.go

.rs

.java

import { Configuration, EnvironmentApi } from 'hanzoai';

const api = new EnvironmentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.putEnvironmentByRepo({ repo: 'repo', install: "<install>", repo: "<repo>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import EnvironmentApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = EnvironmentApi(client).put_environment_by_repo(repo='repo', install="<install>", repo="<repo>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.EnvironmentAPI.PutEnvironmentByRepo(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, environment_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = environment_api::put_environment_by_repo(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.EnvironmentApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new EnvironmentApi(client).putEnvironmentByRepo();

curl -X PUT https://api.hanzo.ai/v1/environment/<repo> \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "install": "<install>",
       "repo": "<repo>"
     }'

MCP reaches environment through the environment tool, which names its 4 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_environments"
         }
       }
     }'

Environment API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousReplace secrets NextList audit