An AI coding agent can help build a ZeyOS service, adapt a form, or automate a business workflow. To do that reliably, it needs more than a description of the desired result. It needs to know which language features exist, which database fields are real, and how to check its work.
ZeyOS has two development paths: native applications written with iXML and Zymba, and external integrations using the API, client, CLI, or MCP server. A good agent setup makes that distinction explicit and gives each path the right validation tools.
The same setup logic works with Kilo Code, Pi, OpenCode, or another coding agent.
Give the agent a project contract
Start with a short instruction document in the project repository. It should tell the agent where to find the references, how the application is organized, what it may execute, and what evidence it must provide before calling a change complete.
We provide copyable ZeyOS project instructions covering iXML, Zymba, database requests, and validation. Merge them into your existing AGENTS.md, or save them as a separate file loaded by your coding agent. Add the application root, local reference paths, relevant examples, and sandbox configuration. Keep credentials in private credential storage.
The shared instructions describe the ZeyOS project contract. The harness controls how that file is loaded, how tools and MCP servers are configured, and which operations require approval. Keep those concerns separate: use the same ZeyOS rules across Kilo Code, Pi and OpenCode, then configure each harness through its supported files and settings. Agent Setup provides the current examples for all three.
Start a fresh task and have the agent identify the instructions and references it found. If it cannot access them, resolve that before asking it to implement a feature.
Make reference lookup part of coding
iXML and Zymba have precise contracts. Familiar-looking syntax is not enough. An agent might generate an if with a condition attribute, call @String.length, or query an account's name field. Those choices look plausible but do not match the ZeyOS references.
Give the agent access to the exact commands and schema entries it needs. The developer guide contains the iXML and Zymba references, database metadata, SDK documentation, and a log of successful and failed execution examples. The website's AI resources provide machine-readable references and smaller indexes for targeted retrieval.
Keep the always-loaded instructions compact. Let the agent retrieve the relevant namespace, class, or table when needed. That leaves more room for the application code and the task itself. Record the reference version or hash so a later failure can be compared against the same evidence.
Treat XML formatting as part of correctness
iXML is executable XML. Escaping, result propagation, and text placement matter. In attribute values, use < for less-than and preserve intentional entity references. Keep the application's indentation and envelope conventions, and avoid reflowing text or embedded content.
This basic example from the guide's execution log is a useful starting point:
<set var="name">iXML</set>
<output>Hello $name</output>
The output is Hello iXML. The variable declaration uses name; $name substitutes its value. A declaration such as <set var="$name"> is invalid.
For Zymba, the symbol index and namespace index expose authoritative declarations with source hashes and JSON pointers. Check the raw parameter and return metadata, static/instance receiver, and annotations. Display signatures are lookup aids; native compilation and requested behavior tests provide different evidence.
A generic XML formatter cannot verify iXML behavior. In particular, mixing literal text with child statements can discard the literal text through result propagation. The agent should understand that behavior before moving or combining statements. The native-code validation guide covers formatting, types, function parameters, and these common failure cases.
Look up database names before writing a query
Database mistakes are especially expensive because a request can be syntactically valid while using the wrong business concept.
Require the agent to resolve every resource, table, column, relationship, and enum before it writes a query. Accounts use lastname and firstname; they do not have a name field. Creating an account requires currency. A visibility filter is appropriate only for resources that have that field; transactions do not.
The ZeyOS CLI already provides useful local checks:
zeyos describe accounts --json
zeyos list accounts --fields ID,lastname --limit 5 --dry-run --json
The first command exposes bundled schema metadata. The second previews a request without sending it. JavaScript integrations can use client.schema.validate(operationId, input) and enable validate: true for API calls.
Client/CLI 1.0.0 and later follow every documented foreign-key hop to the terminal field and check custom keys against an explicit instance-specific contract. Configure customFields in JavaScript or ZEYOS_CUSTOM_FIELDS_FILE for CLI/MCP. Missing definitions are errors; refresh the snapshot when configuration changes. Upgrade client and CLI together, since older releases accepted these paths unchecked. These checks still do not prove permissions, all required inputs or join cardinality, validate native SQL, or compile iXML/Zymba. The setup guide explains which checks apply to each interface.
Choose a model using your own failure cases
Start with a capable model for unfamiliar native code and difficult debugging. Then test a less expensive candidate on the same tasks and references. The setup guide's dated model shortlist gives a starting point without treating a general coding ranking as a ZeyOS benchmark.
A useful trial includes fixing an invalid iXML attribute, checking a Zymba method signature, detecting a missing account currency, rejecting an invented database field, and handling an unknown custom field without guessing. Compare accepted results, repair attempts, elapsed time, and total cost. A cheaper request is not cheaper work if it requires repeated repairs.
Validate without running the code
Use the native compiler when the task is to check iXML or Zymba:
# From an existing linked application; use the changed asset's actual path.
zeysdk compile services/example.ixml
zeysdk lint --all
compile checks one asset; lint --all checks eligible locally present scripts
from the manifest and standard settings. Both send source to the authenticated
platform compiler without executing it. They require network access and a
confirmed target instance. Report the files checked: a lint run with no eligible
files is not evidence that a changed script passed. See the
SDK documentation.
Compiler diagnostics, reference/schema review and behavior tests are separate
checks. Compilation does not prove that dynamic field names are correct, inputs
are complete, or permissions and business behavior are right. zeysdk run
executes code and should only be used when the task calls for execution, in an
authorized sandbox. An inline run also does not establish that a hook, form or
HTTP route works through its actual entry point.
For external workflows, the bundled ZeyOS MCP server gives agents access to discovery, schema descriptions and record queries. Writes are disabled by default. Use the harness-specific connection examples and begin with schema discovery and request previews. Tool permissions and credential scope enforce access; an instruction file alone cannot do that.
Grow automation from verified workflows
Start with a small task whose result you can inspect. Once it works, record the verified pattern and the failure cases that matter. Before making it unattended, define the target instance, permitted operations, record limit, retry budget, and stop conditions.
Design recovery as carefully as the happy path. If a create request times out, the server may already have completed it. Reconcile the result before retrying. Avoid overlapping job runs, verify writes by reading their results, and retain redacted audit information. A transaction does not automatically undo an email or an external HTTP call.
Complete relationship-path validation and explicit tenant custom-field metadata now provide an API preflight. The SDK already supplies native compiler checks. Further improvements can add reference-derived contract checks and a broader regression set built from actual runtime mistakes. These extensions should make uncertainty visible rather than silently accepting what they cannot check.
Use the Agent Setup guide to configure your workspace, copy the project instructions, and give the agent one small ZeyOS task with a clear expected result.