Configure the workspace

agents.md instructions

Provide shared instructions for every harness Session.

On this page

Set shared instructions

Each Environment has one optional agents.md instruction resource, shared by all of its harness Sessions. Use the dedicated resource operations to read, replace, or delete its Markdown content, or edit it in the Platform console. The API details contains the JSON request and response contract and examples. Content is UTF-8 text limited to 32 KiB; an empty document is distinct from an absent resource.

Storage and checkpoint behavior

The resource is stored as /workspace/AGENTS.md in the Environment's RootFS, with no second database copy. File API edits to that path affect the same resource. Forks inherit the selected content, and rollback restores checkpoint content. Operations require a ready initial checkpoint and return a conflict while a Run, rollback, or pending checkpoint prevents file access. Reads and writes resume a paused Sandbox. Deleting an absent resource succeeds.

When instructions apply

Changes apply when the next Run starts, including Runs that resume a native Session. Codex, Pi, Kimi Code, and ZCode load the native Workspace instruction file. For Claude Code 2.1.281 and later, Platform enables native loading of both AGENTS.md and CLAUDE.md; older releases receive the resource content through an appended system prompt. These instructions augment the harness defaults. Repository and subdirectory instruction files retain their native harness behavior.

Create or replace Environment agents.md

PUT /v1/environments/{environmentId}/agents.md

One persistent instruction resource per Environment, shared by all harness Sessions. Stored in the writable RootFS and inherited by forks and checkpoints; rollback restores checkpoint content. Operations require a ready initial checkpoint and return 409 during a Run, rollback, or pending checkpoint. Missing content returns 404 on read; deletion is idempotent. Changes apply to subsequent Runs, including resumed Sessions.

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string · min length 1	Yes	Environment identifier. It must belong to the caller’s account or Project.

Request example

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/agents.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "content": "Use TypeScript. Run the relevant tests before finishing.\n"
}'

Request body · required `application/json`

Markdown instruction content to save in the Environment.

Field	Type and constraints	Required	Description
`content`	string · max length 32768	Yes	Markdown instructions, at most 32 KiB of UTF-8 text.

Example

{
  "content": "Use TypeScript. Run the relevant tests before finishing.\n"
}

Responses

200 Successful response.

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Environment instruction resource metadata and Markdown content.
`data.content`	string · max length 32768	Yeswithin data	Markdown instructions, at most 32 KiB of UTF-8 text.
`data.sizeBytes`	integer · ≥ 0; ≤ 32768	Yeswithin data	UTF-8 or file content size in bytes.
`data.sha256`	string Validation pattern `^[a-f0-9]{64}$`	Yeswithin data	Lowercase hexadecimal SHA-256 digest of the file bytes.

Example

{
  "data": {
    "content": "",
    "sizeBytes": 0,
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

Error responses

400 Invalid request.

application/json

401 Missing or invalid Platform API token.

application/json

404 Resource not found or outside token scope.

application/json

409 Environment file access is temporarily blocked. The error code identifies queued/executing work, checkpoint saving, initialization, rollback, pausing, resuming, or other lock contention. Checkpoint ready does not guarantee the lifecycle lock has been released.

application/json

413 Instruction content exceeds 32 KiB of UTF-8 text.

application/json

415 Unsupported request media type.

application/json

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Verify and remove

Read the resource after updating it to verify the saved content. Delete it to stop applying the shared instructions to subsequent Runs. Deletion does not remove repository-specific instruction files.

Read Environment agents.md

GET /v1/environments/{environmentId}/agents.md

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string · min length 1	Yes	Environment identifier. It must belong to the caller’s account or Project.

Request example

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/agents.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

200 Successful response.

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Environment instruction resource metadata and Markdown content.
`data.content`	string · max length 32768	Yeswithin data	Markdown instructions, at most 32 KiB of UTF-8 text.
`data.sizeBytes`	integer · ≥ 0; ≤ 32768	Yeswithin data	UTF-8 or file content size in bytes.
`data.sha256`	string Validation pattern `^[a-f0-9]{64}$`	Yeswithin data	Lowercase hexadecimal SHA-256 digest of the file bytes.

Example

{
  "data": {
    "content": "",
    "sizeBytes": 0,
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

Error responses

400 Invalid request.

application/json

401 Missing or invalid Platform API token.

application/json

404 Resource not found or outside token scope.

application/json

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Delete Environment agents.md

DELETE /v1/environments/{environmentId}/agents.md

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string · min length 1	Yes	Environment identifier. It must belong to the caller’s account or Project.

Request example

curl -X DELETE \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/agents.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

204 No content.

Empty response body.

Error responses

400 Invalid request.

application/json

401 Missing or invalid Platform API token.

application/json

404 Resource not found or outside token scope.

application/json

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

agents.md instructions

Set shared instructions

Storage and checkpoint behavior

When instructions apply

Create or replace Environment agents.md

Parameters and headers

Request example

Request body · required application/json

Responses

Response body application/json

Error body application/json

Verify and remove

Read Environment agents.md

Parameters and headers

Request example

Responses

Response body application/json

Error body application/json

Delete Environment agents.md

Parameters and headers

Request example

Responses

Error body application/json

Request body · required `application/json`

Response body `application/json`

Error body `application/json`

Response body `application/json`

Error body `application/json`

Error body `application/json`