Coding agents
Your coding agents will read these docs and call the API for you. This page gives them the rules that matter, in the forms they read.
Give your agent the rules
Paste this into your repository’s AGENTS.md or CLAUDE.md, where Codex, Claude Code, Cursor and other agents read project instructions. It covers what agents most often get wrong with an API like this one: idempotency keys, accepted operations and commands that keep running after a disconnect.
# Ortam
Ortam runs commands in Sandboxes: Linux VMs whose disks are saved, so the next job starts with the files in place. Read the docs as Markdown: https://ortam.dev/llms.txt lists every page, and any docs page has a Markdown copy at its address plus .md.
- The API is https://api.ortam.dev, JSON over HTTPS. Send `Authorization: Bearer $ORTAM_API_KEY` on every request. The key acts for the whole organization: never print, log or commit it.
- Every request that changes something needs an `Idempotency-Key` header, a new UUID per action. If the request fails or times out, retry it with the same key; Ortam returns the original outcome instead of acting twice. Reusing a key with different inputs returns 409.
- 202 means accepted, not done. Keep the `operation` and `resource` IDs and read `GET /v1/operations/{id}` until its state is `completed`, `failed` or `unknown`. A passed deadline alone doesn't mean it failed.
- Run a command with `POST /v1/sandboxes/{id}/executions` and `argv`. There is no shell unless you run one: `["/bin/bash", "-lc", "npm test"]`. A stopped Sandbox starts first. Read `GET /v1/executions/{id}` for its state and exit code; disconnecting never cancels it.
- Ortam never reruns a command. If an outcome is `unknown`, decide whether running it again is safe.
- Stop ends all work in the Sandbox, including commands still running. If you need a command's result, read it to the end first.
- Files you write to the Sandbox's disk are saved and copied into Snapshots, secrets included. Credentials Ortam delivers for Connections live in temporary storage and aren't, unless a program copies them onto the disk. Don't write credentials into a Sandbox you will copy.
- Errors are JSON, `{"error": "…"}`, or plain text when the request body couldn't be read: 400 an invalid request or body, 401 a missing or invalid key, 404 not in your organization, 409 a conflict with the Sandbox's state or a reused idempotency key, 422 JSON that doesn't fit the route (a missing, unknown or wrongly typed field), 503 authorization couldn't be checked (retry with the same idempotency key).
- Routes for output, files and Connections aren't published yet. Don't guess them.
Install the Agent Skill
The same rules are an Agent Skill: agents that support skills load it when a task involves Ortam, instead of reading it on every task. The skill is at https://ortam.dev/.well-known/agent-skills/ortam/SKILL.md, and it’s listed, with its SHA-256 digest, in the discovery index at https://ortam.dev/.well-known/agent-skills/index.json, so tools that discover skills from a site’s address find it.
Where agents find the docs
- llms.txt
- An index of every docs page and post, with what Ortam is and its key facts first.
- llms-full.txt
- All of the docs in one file.
- Markdown copies
- Any docs page or post at its address plus .md, such as /docs/commands.md. A request whose Accept header prefers text/markdown gets the Markdown at the page’s own address.
- API catalog
- https://ortam.dev/.well-known/api-catalog points to the API reference, as RFC 9727 describes.
The API reference lists every route, field and record. Routes for output, files and Connections aren’t published yet, so an agent shouldn’t guess them.